diff --git a/README.md b/README.md new file mode 100644 index 00000000..f51e5d04 --- /dev/null +++ b/README.md @@ -0,0 +1,5 @@ +# Welcome to the 5G-MAG Reference Tools Repositories + +This repository is meant as an entry point to all the repositories related to the 5G-MAG Reference Tools. It serves as an umbrella for documentation, practical guidelines and examples of applications that can be built with the software packages and also in combination with other platforms. + +All the relevant information is available in: https://5g-mag.github.io/Getting-Started/ diff --git a/_config.yml b/_config.yml index 874c1388..348d6fae 100644 --- a/_config.yml +++ b/_config.yml @@ -56,7 +56,6 @@ callouts: title: Warning color: red - # Footer content # appears at the bottom of every page's main content @@ -64,7 +63,7 @@ callouts: back_to_top: true back_to_top_text: "Back to top" -footer_content: "Copyright © 5G-MAG" +footer_content: "Copyright © 5G-MAG MEDIA ACTION GROUP" # Footer last edited timestamp last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss new file mode 100644 index 00000000..be8551a8 --- /dev/null +++ b/_sass/custom/custom.scss @@ -0,0 +1,3 @@ +.side-bar { + width: 30%; +} diff --git a/assets/images/5g-mag-logo-with-text.png b/assets/images/5g-mag-logo-with-text.png index d7ffaf36..017da005 100644 Binary files a/assets/images/5g-mag-logo-with-text.png and b/assets/images/5g-mag-logo-with-text.png differ diff --git a/assets/images/5g-mag-reference-tools.png b/assets/images/5g-mag-reference-tools.png index ed6257fe..9646e619 100644 Binary files a/assets/images/5g-mag-reference-tools.png and b/assets/images/5g-mag-reference-tools.png differ diff --git a/index.md b/index.md index 839b760d..f763f371 100644 --- a/index.md +++ b/index.md @@ -5,7 +5,7 @@ nav_order: 0 has_children: true --- -5g-mag +5g-mag # Overview diff --git a/pages/5g-media-streaming/repositories.md b/pages/5g-media-streaming/repositories.md index 11ae8bf9..cb517172 100644 --- a/pages/5g-media-streaming/repositories.md +++ b/pages/5g-media-streaming/repositories.md @@ -2,12 +2,17 @@ layout: default title: Repositories parent: 5G Downlink Media Streaming -has_children: false +has_children: true nav_order: 3 --- # ⭐ Related repositories -Please note that 5G Media Streaming makes use of other generic [5G Core Network components](https://jordijoangimenez.github.io/Getting-Started/pages/5g-core-network-components/) +Please note that 5G Media Streaming makes use of other generic [5G Core Network components](https://5g-mag.github.io/Getting-Started/pages/5g-core-network-components/) + +## 5GMS Application Provider: [rt-5gms-application-provider](https://github.com/5G-MAG/rt-5gms-application-provider) +* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-5gms-application-provider#readme) +* [Releases](https://github.com/5G-MAG/rt-5gms-application-provider/releases) +* [Projects](https://github.com/5G-MAG/rt-5gms-application-provider/projects?query=is%3Aopen) ## 5GMSd Application Function: [rt-5gms-application-function](https://github.com/5G-MAG/rt-5gms-application-function) * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-5gms-application-function#readme) diff --git a/pages/5g-media-streaming/features.md b/pages/5g-media-streaming/repositories/features5GMSAF.md similarity index 57% rename from pages/5g-media-streaming/features.md rename to pages/5g-media-streaming/repositories/features5GMSAF.md index 2b26f6f7..022f9e4a 100644 --- a/pages/5g-media-streaming/features.md +++ b/pages/5g-media-streaming/repositories/features5GMSAF.md @@ -1,83 +1,144 @@ --- layout: default -title: Features -parent: 5G Downlink Media Streaming +title: Features 5GMS AF +parent: Repositories +grand_parent: 5G Downlink Media Streaming has_children: false -nav_order: 1 +nav_order: 0 --- -# List of features under implementation +# 5GMSd Application Function Supported Features -The following describes the features of the Application Function that have been implemented, due to be implemented or not planned -yet. - -## Implemented in latest release (v1.2.0) - -- Reference point M1 (AP <=> AF) - - Provisioning Sessions (TS 26.512 v17.3.0) - - Content Protocols Discovery (TS 26.512 v17.3.0) - - Server Certificates Provisioning (TS 26.512 v17.3.0) - - Content Hosting Provisioning (TS 26.512 v17.3.0) -- Reference point M3 (AS <=> AF) - - Server Certificates Provisioning - - Content Hosting Provisioning -- Reference point M5 (UE <=> AF) - - Service Access Information (TS 26.512 v17.3.0) - -## Being worked on for pending releases - -This is a list of features being worked on for upcoming releases (and who is primarily working on that feature): - -- Reference point M1 (AP <=> AF) - - Uplift to TS 26.512 V17.4.0 (BBC) - - Policy Templates Provisioning (BBC) - - Uplift to TS 26.512 V17.5.0 (BBC) - - QoE Metrics Reporting Provisioning (Fraunhofer Fokus) -- Reference point M5 (UE <=> AF) - - Network Assistance (BBC) - - Dynamic Policies (BBC) - - QoE Metrics Reporting (Fraunhofer Fokus) - - Consumption Reporting (Qualcomm) -- 5GMBS seamless switching () - -## Unimplemented - -The following is a list of possible areas of the project to work on, noting which reference point(s) each is for or where a component -resides: - -- Data Collection AF -- Direct Data Collection Client (UE) -- Reference point M1 (AP <=> AF) - - Edge Computing integration - - Content Preparation Template Provisioning - - Consumption Reporting Provisioning - - Event Data Processing Provisioning -- Reference point M3 (AS <=> AF) - - Life-cycle management (heartbeat/registration/deregistration) -- Reference point M5 (UE <=> AF) -- Reference point R4 (AS <=> AF) - - Media Streaming Access Reporting -- Reference point R6 (AP <=> AF) - - Exposure of Dynamic Policy invocation events - - Exposure of Network Assistance invocation events - - Exposure of QoE Metrics Reporting events - - Exposure of Consumption Reporting events - - Exposure of Media Streaming Access Report events - -# Supported Features in the Software Releases - -## 5GMSd Application Function - -The release versions of the 5GMSd Application Function support differing sets of reference points, as described by the different +The release versions of the 5GMSd Application Function support differing sets of interfaces, as described by the different versions of the 3GPP specifications, and differing levels of feature support for those interfaces. The page attempts to capture the feature sets and specification versions for each release, starting with the most recent release or upcoming releases. -### Key +## Key -Where a feature of the specifications is supported the entry will be marked with ☑ and where it is unimplemented in that +Where a feature of the specifications is supported the entry will be marked with ☑, where it is being worked on and slated for the next release the feature will be marked with ✎ and where it is unimplemented in that version the feature will be marked with ☐. -### Upcoming Release v1.3.0 +## Upcoming Release v1.4.0 (development branch) + + + + + + + + + + + + + + + + + +
Interface reference pointSpecifications & VersionsProtocolsFeatures
M1 (server)
    +
  • TS 26.501 v17.6.0
    • +
  • TS 26.512 v17.6.0
    • +
    +
  • ☑ HTTP/1.1
    • +
  • ☐ HTTP/2.0
    • +
  • ☑ HTTP/1.1 over SSL/TLS
    • +
  • ☐ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☑ Content Hosting Provisioning
    • +
  • ☑ Content Protocols Discovery
    • +
  • ☑ Provisioning Sessions
    • +
  • ☑ Server Certificates Provisioning
    • +
  • ☑ Consumption Reporting Provisioning
    • +
  • ☐ Content Preparation Templates Provisioning
    • +
  • ☐ Edge Resources Provisioning
    • +
  • ☐ Event Data Processing Provisioning
    • +
  • ✎ Metrics Reporting Provisioning
    • +
  • ☑ Policy Templates Provisioning
    • +
M3 (client)
    +
  • 5G-MAG prototype
    • +
    +
  • ☑ HTTP/1.1
    • +
  • ☑ HTTP/2.0
    • +
  • ☑ HTTP/1.1 over SSL/TLS
    • +
  • ☑ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☑ Content Hosting Provisioning
    • +
  • ☑ Server Certificates Provisioning
    • +
M5 (server)
    +
  • TS 26.501 v17.6.0
    • +
  • TS 26.512 v17.6.0
    • +
    +
  • ☑ HTTP/1.1
    • +
  • ☐ HTTP/2.0
    • +
  • ☑ HTTP/1.1 over SSL/TLS
    • +
  • ☐ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☑ Service Access Information
    • +
  • ☑ Consumption Reporting
    • +
  • ☑ Dynamic Policies
    +   Service Data Flow Description Methods:
      +
    • ☐ 2 Tuple
      • +
    • ☑ 5 Tuple
      • +
    • ☐ ToS
      • +
    • ☐ Flow Label
      • +
    • ☐ Domain Name
      • +
    • +
  • ✎ Metrics Reporting
    • +
  • ☑ Network Assistance
      +
    • ☐ Throughput Estimation
      • +
    • ☑ Delivery Boost
      • +
    • +
N5 (Npcf client/server)
    +
  • TS 29.514 v17.8.0
    • +
    +
  • ☑ HTTP/2.0
    • +
  • ☑ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☑ Policy Authorization
    • +
  • ☑ Policy Authorization Notifications
    • +
N33 (client)
    +
  • TS 29.591 v17.9.0
    • +
    +
  • ☐ HTTP/2.0
    • +
  • ☐ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☐ Event Exposure
    • +
R4 (server)
    +
  • TS 26.512 v17.6.0
    • +
    +
  • ☐ HTTP/1.1
    • +
  • ☐ HTTP/2.0
    • +
  • ☐ HTTP/1.1 over SSL/TLS
    • +
  • ☐ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☐ Media Streaming Access
    • +
R5/R6 (client/server)
    +
  • TS 26.512 v17.6.0
    • +
  • TS 29.517 v17.9.0
    • +
    +
  • ☐ HTTP/1.1
    • +
  • ☐ HTTP/2.0
    • +
  • ☐ HTTP/1.1 over SSL/TLS
    • +
  • ☐ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☐ Media Streaming QoE Event
    • +
  • ☐ Media Streaming Consumption Event
    • +
  • ☐ Media Streaming Network Assistance Invocation Event
    • +
  • ☐ Media Streaming Dynamic Policy Invocation Event
    • +
  • ☐ Media Streaming Access Event
    • +
  • ☐ Event Subscription
    • +
Nbsf (client)
    +
  • TS 29.513 v17.10.0
    • +
  • TS 29.521 v17.8.0
    • +
    +
  • ☑ HTTP/2.0
    • +
  • ☑ HTTP/2.0 over SSL/TLS
    • +
    +
  • ☑ Binding Information Retrieval
    • +
+ +## Release v1.3.0 @@ -158,7 +219,7 @@ version the feature will be marked with ☐.
Interface reference pointSpecifications & VersionsProtocolsFeatures
-### Release v1.2.0 +# Release v1.2.0 @@ -239,7 +300,7 @@ version the feature will be marked with ☐.
Interface reference pointSpecifications & VersionsProtocolsFeatures
-### Release v1.1.0 +# Release v1.1.0 @@ -320,3 +381,69 @@ version the feature will be marked with ☐.
Interface reference pointSpecifications & VersionsProtocolsFeatures
+# Features + +The following describes the features of the Application Function that have been implemented, due to be implemented or not planned +yet. + +## Implemented in the upcoming release (v1.4.1) + +- Everything from v1.4.0 plus... +- Interface at M1 (AP <=> AF) + - Metrics Reporting Provisioning (TS 26.512 v17.7.0 + fixes) + - Python command line tools moved to [rt-5gms-application-provider](https://github.com/5G-MAG/rt-5gms-application-provider) repository +- Interface at M5 (UE <=> AF) + - Metrics Reporting (TS 26.512 v17.7.0 + fixes) + +## Implemented in the latest release (v1.4.0) + +- Interface at M1 (AP <=> AF) + - Provisioning Sessions (TS 26.512 v17.4.0) + - Content Protocols Discovery (TS 26.512 v17.4.0) + - Server Certificates Provisioning (TS 26.512 v17.4.0) + - Content Hosting Provisioning (TS 26.512 v17.4.0) + - Consumption Reporting Provisioning (TS 26.512 v17.7.0) + - Dynamic Policy Templates Provisioning (TS 26.512 v17.7.0) +- Interface at M3 (AS <=> AF) + - Server Certificates Provisioning + - Content Hosting Provisioning +- Interface at M5 (UE <=> AF) + - Service Access Information (TS 26.512 v17.7.0) + - Consumption Reporting (TS 26.512 v17.7.0) + - Network Assistance (TS 26.512 v17.7.0) + - Delivery Boost only + - Dynamic Policies (TS 26.512 v17.7.0) + - 5 Tuple Service Flow Description method only. +- Uplift of other interfaces to TS 26.512 v17.7.0 + +## Being worked on for pending releases + +This is a list of features being worked on for upcoming releases of the 5GMS Application Function (and who is primarily working on that feature): + +- Data Collection AF (BBC) + - Internal AF interface (originating at M5 (UE <=> AF)) + - Collection of Metrics Reports + - Collection of Consumption Reports + - Interface at R4 (AS <=> AF) + - Media Streaming Access Reporting + - Interface at R5/R6 (AP <=> NWDAF/AF) + - Metrics Report Events + - Consumption Report Events + - Network Assistance Invocation Events + - Dynamic Policy Invocation Events + - Media Streaming Access Report Events +- 5GMBS seamless switching () + +## Unimplemented + +The following is a list of possible areas of the project to work on noting which interfaces each is for or where a component +resides: + +- Direct Data Collection Client (UE) +- Interface at M1 (AP <=> AF) + - Edge Computing integration + - Content Preparation Template Provisioning + - Event Data Processing Provisioning +- Interface at M3 (AS <=> AF) + - Lifecycle management (heartbeat/registration/deregistration) + - Hosting activation/deactivation diff --git a/pages/5g-media-streaming/specifications.md b/pages/5g-media-streaming/specifications.md index 787d2172..b843f4cc 100644 --- a/pages/5g-media-streaming/specifications.md +++ b/pages/5g-media-streaming/specifications.md @@ -6,6 +6,9 @@ has_children: false nav_order: 0 --- -# 📑 Specifications and relevant references -* Information about relevant specifications can be found at the [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/5G-Downlink-Media-Streaming-Architecture-(5GMSd):-Relevant-Specifications) -* A list of relevant 3GPP Work Items can be found at [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/5G-Downlink-Media-Streaming-Architecture-(5GMSd):-Relevant-Work-Items) +# 5G Media Streaming +## 📑 Specifications and relevant references +* Information about relevant specifications can be found in this [page](https://5g-mag.github.io/Standards/pages/5g-media-streaming/5g-media-streaming-specifications.html) + +## 📑 Relevant Work Items +* A list of relevant 3GPP Work Items can be found in this [page](https://5g-mag.github.io/Standards/pages/5g-media-streaming/5g-media-streaming-workitems.html) diff --git a/pages/5g-media-streaming/testing.md b/pages/5g-media-streaming/testing.md new file mode 100644 index 00000000..4afbed55 --- /dev/null +++ b/pages/5g-media-streaming/testing.md @@ -0,0 +1,54 @@ +--- +layout: default +title: Testing +parent: 5G Downlink Media Streaming +has_children: true +nav_order: 3 +--- +# 🚧 Testing + +## Installation of the 5GMS AF as a Local User +Follow the instructions in this [page](testing/installation-local-user-5GMSAF.html) for setting up a test environment without requiring full +system installation. + +## Installation of the 5GMS AF as a System Service +Follow the instructions in this [page](testing/installation-system-service-5GMSAF.html) for setting up a full system installation. + +## Testing APIs + +### Testing: M1 Interface + +The details of these tests change with different versions of the 5GMSd Application Function. + +If you are testing the v1.2.x versions then please visit the [Testing the M1 Interface on v1.2.0](testing/testing-m1-v120.html) +page. + +If you are testing the M1 interface on 5GMSd Application Function v1.3.0 to v1.4.0 then please visit the +[Testing the M1 Interface on v1.3.0](testing/testing-m1-v130.html) page. + +For testing the M1 interface on 5GMSd Application Function v1.4.1 or later, then please visit the +[Testing the M1 Interface on v1.4.1](testing/testing-m1-v141.html) page. + +### Testing: M3 Interface + +Depending on which version of the 5GMSd Application Function you wish to test, the commands to test the interface at reference point M3 change. + +If you wish to test 5GMSd Application Function v1.1.x then please see the [Testing the M3 Interface on v1.1.0](testing/testing-m3-v110.html) page. + +For versions after v1.1.x (i.e. v1.2.0 and above) please use the [Testing the M3 Interface on v1.2.0](testing/testing-m3-v120.html) page. + +### Testing: M5 Interface + +The details of these tests change with different versions of the 5GMSd Application Function. + +If you are testing versions up to v1.1.x then please visit the [Testing: M5 Interface on v1.0.0](testing/testing-m5-v100.html) page. + +If you are testing the M5 interface on 5GMSd Application Function v1.2.x please visit the +[Testing the M5 Interface on v1.2.0](testing/testing-m5-v120.html) page. + +If you are testing the M5 interface on 5GMSd Application Function v1.3.0 or later please visit the +[Testing the M5 Interface on v1.3.0](testing/testing-m5-v130.html) page. + +### Testing with Postman + +Postman is a popular API development and testing tool that allows users to create, send, and manage HTTP requests. Postman comes in very handy when testing and working with the M1 and M5 interfaces of the Application Function. Plese visit the [Testing with Postman](testing/testing-postman.html) diff --git a/pages/5g-media-streaming/testing/compatibility.md b/pages/5g-media-streaming/testing/compatibility.md new file mode 100644 index 00000000..5be9b902 --- /dev/null +++ b/pages/5g-media-streaming/testing/compatibility.md @@ -0,0 +1,24 @@ +--- +layout: default +title: Compability 5GMS components +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 0 +--- + +# Compatibility between 5GMSd components + +Some versions of the 5GMSd Application Function will only work with particular versions of the 5GMSd Application Server and 5GMSd Media Session Handler. + +This page describes which versions will work with each other. + +| 5GMSd AF release | 5GMSd AS release | 5GMSd Media Session Handler | +| --- | --- | --- | +| [v1.0.0](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.0.0) | [v1.0.0](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.0.0) and [v1.0.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.0.1) | - | +| [v1.0.1](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.0.1) | [v1.0.0](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.0.0) and [v1.0.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.0.1) | - | +| [v1.1.0](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.1.0) | [v1.1.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.1.1) | - | +| [v1.2.0](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.2.0) | [v1.1.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.1.1) | - | +| [v1.2.1](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.2.1) | [v1.1.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.1.1) | - | +| [v1.3.0](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.3.0) | [v1.1.2](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.1.2), [v1.2.0](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.2.0) and [v1.2.1](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.2.1) | - | +| [v1.4.0](https://github.com/5G-MAG/rt-5gms-application-function/releases/tag/rt-5gms-application-function-v1.4.0) | [v1.3.0](https://github.com/5G-MAG/rt-5gms-application-server/releases/tag/rt-5gms-application-server-1.3.0) | - | diff --git a/pages/5g-media-streaming/testing/development-AS.md b/pages/5g-media-streaming/testing/development-AS.md new file mode 100644 index 00000000..14e02424 --- /dev/null +++ b/pages/5g-media-streaming/testing/development-AS.md @@ -0,0 +1,275 @@ +--- +layout: default +title: Developing the 5GMS AS +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 4 +--- + +CONTENT TO BE CHECKED + +In this directory you will find files to assist with development and testing of +the 5G-MAG Reference Tools 5GMS Application Server (AS). + +Files in this repository: +- ATTRIBUTION_NOTICE - List of 3rd party software used when running the 5GMS application server. +- LICENSE - The software license for this project. +- README.md - Project README file. +- pyproject.toml - The Python project description for building and installing the application. +- build_scripts/ - Scripts used when building the python project. + - api.mustache - openapi-generator template file to pass operations onto methods in the class defined in src/rt_5gms_as/server.py. + - backend.py - build backend wrapper to trigger extra build actions. + - generate_5gms_as_openapi - Will generate the OpenAPI python modules if not already present. + - M3_merged.yaml - OpenAPI YAML wrapper file to merge the M3 interface files into one for API bindings generation. + - openapi-generator-config.yaml.in - openapi-generator configuration file template. +- docs/ - Development documentation and examples. + - README.md - This document. + - example-application-server.conf - An application configuration which documents the defaults and meaning for each application configuration option. +- external/ - Directory containing submodule mount points. + - rt-common-shared/ - The common shared examples and scripts. +- src/ - The application source modules. + - rt_5gms_as/ - The main Python module for this application + - app.py - Application entry point. + - exceptions.py - Application specific Exception class definitions. + - context.py - Module for the application Context class. + - openapi_5g/ - Python bindings generated by openapi-generator-cli from the 5G APIs. Note: This directory is not present in the tree until `build_scripts/generate_openapi` is run. + - proxies/ - Contains the web server/proxy detection and configuration classes and any data files they need. + - proxy_factory.py - Factory module to pick a suitable web server/proxy. + - server.py - M3 Server implementation. + - utils.py - Common utility functions for the web server/proxy classes. +- tests/ - Regression and build acceptance tests and other testing tools. + - examples/ - Example configurations to go along with the tests. + +Running the example without building +------------------------------------ +Make sure that git, java, wget and nginx are installed on the local system and +can be found on the current command path (`$PATH`). +``` +sudo apt install git wget nginx default-jdk python3-regex +``` + +Generate the OpenAPI python modules (these are not part of the source +distribution). Read documentation below on "Regenerating the 5G API bindings": +``` +cd ~/rt-5gms-application-server +build_scripts/generate_5gms_as_openapi +``` + +Create a configuration to run the application server as a local, unprivileged, +user. +``` +mkdir ~/.rt_5gms +cat > ~/.rt_5gms/application-server.conf < + m3_client_cli.py -c | --certificate (add|update) + m3_client_cli.py -c | --certificate delete + m3_client_cli.py -H | --content-hosting-configuration + m3_client_cli.py -H | --content-hosting-configuration (add|update) + m3_client_cli.py -H | --content-hosting-configuration delete + m3_client_cli.py -H | --content-hosting-configuration purge [] + +Parameters: + connect Hostname:Port of the server providing M3. + provisioning-session-id Provisioning Session Identifier. + certificate-id Certificate Identifier. + pem-file Server PEM format X.509 public certificate, private key and intermediate CA certificates. + content-hosting-configuration-json-file + Filename of a ContentHostingConfiguration in JSON format. + pattern Regular expression to match the cache entry URL paths to delete. + +Options: + -h --help Display the command help + -v --version Display command version + -c --certificate List known certificates or perform a certificate operation. + -H --content-hosting-configuration + List known ContentHostingConfigurations or perform an operation on ContentHostingConfigurations. +``` + +This can be used instead of the AF to configure a running AS. + +### Prerequisite packages + +These testing scripts require a few more Python 3 modules to be installed, beyond what is brought in as requirements when the when the application server is installed. + +The extra modules are: `docopt`, `aiofiles` and `httpx[http2]`. + +These can be installed on ubuntu using: +```bash +apt install python3-docopt python3-aiofiles python3-httpx python3-h2 +``` +...or on most distributions by using the python `pip` module: +``` +python3 -m pip install docopt aiofiles 'httpx[http2]' +``` + +### Running the Application Server for testing with `m3_client_cli.py` + +When running any of the following tests the Application Server must be running first. The exact command will depend on how you installed the Application Server or whether you are [running directly without building](#running-the-example-without-building). + +#### Running from a virtual Python environment installation + +If the AS you are testing has been installed in a virtual Python environment, as described in the [Development and Testing](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) wiki page, then you would simply run the AS from the virtual environment using your local configuration file. For example: + +```bash +cd ~/rt-5gms-application-server +venv/bin/5gms-application-server -c local-dev.conf +``` + +#### Running a system wide AS installation + +If the Application Server under test has been installed as a system process, using a command like `sudo python3 -m pip install .` or `sudo python3 -m pip install rt-5gms-application-server-1.X.X.tar.gz`, then you can run the AS as root. For example: + +```bash +sudo 5gms-application-server +``` + +### To configure a simple HTTP Application Server + +Make sure the AS is running first (see ["Running the Application Server for testing with `m3_client_cli.py`"](#running-the-application-server-for-testing-with-m3_client_clipy) above). + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 add ps1 tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json +``` +This should respond with a "Success!" message, and NGINX should now be running on port 8080 using the example Big Buck Bunny configuration. You can check the NGINX configuration in `/tmp/rt_5gms_as.conf`. + +### To configure an HTTPS Application Server + +Make sure the AS is running first (see ["Running the Application Server for testing with `m3_client_cli.py`"](#running-the-application-server-for-testing-with-m3_client_clipy) above). + +This requires that the server certificate is pushed to the Application Server before the content hosting configuration is. + +To generate server certificates, ensure that `openssl` is installed (e.g. `apt -y install openssl`), and then: +```bash +cd ~/rt-5gms-application-server +external/rt-common-shared/5gms/scripts/make_self_signed_certs.py tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json tests/examples/Certificates.json +``` + +The 5GMS Application Server stores the certificates it has been configured with in a certificates cache. This cache is reloaded when the Application Server starts up, so it will remember certificates from previous runs. + +The 5GMS Application Server can be checked for what certificates it already has by using the command: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 +``` + +To push a new certificate (with id "testcert1" using the generated certificate file): +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 add testcert1 tests/examples/certificate-1.pem +``` + +...or to update an existing certificate: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 update testcert1 tests/examples/certificate-1.pem +``` + +Now the Content Hosting Configuration can be pushed: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 add ps1 tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json +``` +This should result in "Success!" and NGINX will now be listening on "https://localhost:8443/...". + +To start both HTTPS and HTTP reverse proxies for the Big Buck Bunny content, substitute the ContentHostingConfiguration above for the `tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_http_and_https.json` file, or update the configuration using: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 update ps1 tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_http_and_https.json +``` + +Note: Following these instructions will create a self-signed certificate for localhost in `~/rt-5gms-application-server/tests/examples/certificate-1.pem`, this certificate will not pass normal CA verification so to access the URL you need to turn off SSL validation or accept the self-signed certificate in your browser or media player application. + +Regenerating the 5G API bindings +-------------------------------- +The `build_scripts/generate_5gms_as_openapi` script will use wget, git and java to download the openapi-generator tool, the 5G OpenAPI YAML and generate the `rt_5gms_as.openapi_5g` Python module package. The script will only do this if the `src/rt_5gms_as/openapi_5g` directory does not already exist. + +Therefore to regenerate the API bindings you first need to remove the old bindings: +``` +cd ~/rt-5gms-application-server +rm -rf src/rt_5gms_as/openapi_5g +``` + +Then run the generator script: +``` +~/rt-5gms-application-server/build_scripts/generate_5gms_as_openapi +``` + +For reference (or if it is desirable to recreate the steps manually) the `generate_5gms_as_openapi` script performs the following actions: +- Uses `wget` to fetch version 6.0.1 of the [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator-cli). + - e.g. `wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.0.1/openapi-generator-cli-6.0.1.jar -O openapi-generator-cli.jar` +- Uses `git` to clone the [5G OpenAPI repository](https://forge.3gpp.org/rep/all/5G_APIs.git). + - e.g. `git clone -b REL-17 https://forge.3gpp.org/rep/all/5G_APIs.git` +- Copies in the API override files + - e.g. `cp -f ~/rt-5gms-application-server/external/rt-common-shared/5gms/5G_APIs-overrides/*.yaml ~/rt-5gms-application-server/build_scripts/M3_merged.yaml 5G_APIs/` +- Uses the openapi-generator-cli, downloaded in the first step, to generate the API bindings. + - e.g. `mkdir 5g-api-python; java -jar openapi-generator-cli.jar generate -i 5G_APIs/TS26512_M1_ContentHostingProvisioning.yaml -g python --additional-properties packageName=rt_5gms_as.openapi_5g,projectName=openapi-5g -o 5g-api-python; java -jar openapi-generator-cli.jar generate -t ~/rt-5gms-application-server/build_scripts -i 5G_APIs/M3_merged.yaml -g python --additional-properties packageName=rt_5gms_as.openapi_5g,projectName=openapi-5g -o 5g-api-python` +- Copies the API Python package to the `src/rt_5gms_as/openapi_5g` directory. + - e.g. `cp -r 5g-api-python/rt_5gms_as/openapi_5g ~/rt-5gms-application-server/src/rt_5gms_as/` + diff --git a/pages/5g-media-streaming/testing/installation-local-user-5GMSAF.md b/pages/5g-media-streaming/testing/installation-local-user-5GMSAF.md new file mode 100644 index 00000000..639db522 --- /dev/null +++ b/pages/5g-media-streaming/testing/installation-local-user-5GMSAF.md @@ -0,0 +1,161 @@ +--- +layout: default +title: Installation 5GMS AF as Local User +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 1 +--- + +# Testing the 5GMSd Application Function as a Local User + +**TODO: Intro** + +## Build Dependencies + +Before building the 5GMSd Application Function, there are a few build dependencies that are needed. + +The following are needed: +- **Commands** + - bison + - C compiler + - curl + - flex + - git + - java + - meson (version 0.63.0 or higher)[\[1\]](#footnote-1) + - ninja + - pip + - python3 + - wget +- **Development libraries** + - sctp + - gnutls + - yaml + - nghttp2 + - talloc + - microhttpd + - curl + - mongo DB + - openssl + - gcrypt + - tins + - idn +- **Python modules** + - venv + - yaml + +Notes: + - [1]: `meson` must be at least version 0.63.0 to patch open5gs properly, therefore it is suggested that this be installed using the python pip module to pull the latest version rather than relying on the packaged version from your operating system. + +These can be installed using your system package manager, for example: + +**Ubuntu and derivatives** +```bash +sudo apt install bison build-essential curl flex git default-jdk ninja-build wget python3-pip python3-venv python3-setuptools python3-wheel python3-yaml libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev libnghttp2-dev libmicrohttpd-dev libcurl4-gnutls-dev libnghttp2-dev libtins-dev libtalloc-dev +sudo python3 -m pip install build meson +``` + +## Retrieving the source + +When developing always use the `development` branch of the 5GMSd Application Function. + +If you are intending to commit code back to the project then we advise creating your own "Fork" of the repository at , and working on your own fork. + +To clone the source use: + +```bash +cd +git clone -b development --recurse-submodules git@github.com:${github_username}/rt-5gms-application-function.git +``` + +Where `${github_username}` is your GitHub user name. + +If you are not intending committing changes back to the repository (only testing the latest development version) then you can obtain a clone using: + +```bash +cd +git clone -b development --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-function.git +``` + +If you wish to commit back changes then these should be pushed to a branch on your fork and PR raised to submit the changes back to the development branch of the 5G-MAG repository. + +## Building + +```bash +cd ~/rt-5gms-application-function +meson setup --prefix=`pwd`/install build +ninja -C build +``` + +## Installing + +If you are upgrading from one release to the next then it is advisable to delete the old installed `msaf.yaml` configuration and +replace it with a new one. To delete the old installed configuration use: + +```bash +cd ~/rt-5gms-application-function +rm -f install/etc/open5gs/msaf.yaml +``` + +To install the Application Function, its default configuration and supporting scripts: + +```bash +cd ~/rt-5gms-application-function +meson install -C build --no-rebuild +``` + +It is advisable to review the configuration file in `~/rt-5gms-application-function/install/etc/open5gs/msaf.yaml` before running +the 5GMSd Application Function for the first time after installation. + +## Configuring + +The configuration can be found in `~/rt-5gms-application-function/install/etc/open5gs/msaf.yaml`. Edit this YAML file to change the operating configuration of the 5GMSd Application Function. + +See the [Configuring the Application Function](Configuring-the-Application-Function) page for more details on the settings. + +## Running + +Once the configuration has been set, execute the 5GMSd Application Function using: + +```bash +~/rt-5gms-application-function/install/bin/open5gs-msafd +``` + +For v1.2.0 to v1.4.0: + + To run the `m1-session` tool with a local user installation the python path for the user installed module needs to be included in + the `PYTHONPATH` environment variable. + + ```bash + PYTHONPATH=`find ~/rt-5gms-application-function/install -type d '(' -name 'site-packages' -o -name 'dist-packages' ')' -print` export PYTHONPATH + ``` + + The default configuration for the `m1-session` tool will try to write the persistent store to `/var/cache/rt-5gms/m1-client`. This may not be accessible as a local user and therefore it is a good idea to change the `data_store` configuration setting to a place where the local user can write to: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session configure set data_store ~/m1-client-data-store + ``` + +For v1.4.1 and above: + + The `m1-session` tool has moved to the [rt-5gms-application-provider](https://github.com/5G-MAG/rt-5gms-application-provider) + repository. Please follow the instructions in that repository for manual installation of the M1 python tools and classes to + install the `msaf-configuration`, `m1-session` and `m1-client` tools either to your system or to a virtual python environment. + + If you have installed the tools in the python virtual environment then activate the environment before proceeding, for example: + + ```bash + source venv/bin/activate + ``` + + Then you can change the data store directory, for example: + + ```bash + m1-session configure set data_store ~/m1-client-data-store + ``` + +## Stopping + +Press CTRL-C on the terminal from which the 5GMSd Application Function is running. + diff --git a/pages/5g-media-streaming/testing/installation-system-service-5GMSAF.md b/pages/5g-media-streaming/testing/installation-system-service-5GMSAF.md new file mode 100644 index 00000000..70689a20 --- /dev/null +++ b/pages/5g-media-streaming/testing/installation-system-service-5GMSAF.md @@ -0,0 +1,239 @@ +--- +layout: default +title: Installation 5GMS AF as System Service +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 2 +--- +# Installing the 5GMSd Application Function as a System Service + +## Install dependencies + +```bash +sudo apt install git python3-pip python3-venv python3-setuptools python3-wheel ninja-build build-essential flex bison git libsctp-dev libgnutls28-dev libgcrypt-dev libssl-dev libidn11-dev libmongoc-dev libbson-dev libyaml-dev libnghttp2-dev libmicrohttpd-dev libcurl4-gnutls-dev libnghttp2-dev libtins-dev libtalloc-dev curl wget default-jdk +sudo python3 -m pip install build meson +``` + +## Downloading + +Release tar files can be downloaded from . + +The source can be obtained by cloning the github repository. + +For example to download the latest release you can use: + +```bash +cd ~ +git clone --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-function.git +cd rt-5gms-application-function +git submodule update +``` + +## Build the 5GMSd Application Function + +The build process requires a working Internet connection as the API files are retrieved at build time. + +To build the 5GMSd Application Function from the source: + +```bash +cd ~/rt-5gms-application-function +meson build +ninja -C build +``` + +**Note:** Errors during the `meson build` command are often caused by missing dependancies or a network issue while trying to retrieve the API files and `openapi-generator` JAR file. See the `~/rt-5gms-application-function/build/meson-logs/meson-log.txt` log file for the errors in greater detail. Search for `generator-5gmsaf` to find the start of the API fetch sequence. + +## Installing + +To install the built Application Function as a system process: + +```bash +cd ~/rt-5gms-application-function/build +sudo meson install --no-rebuild +``` + +## Configuration of streams (v1.3.0 and above) + +To assist with runtime configuration of the Application Function when it is started as a Systemd service, there is a utility at `/usr/local/bin/msaf-configuration`. This utility uses two configuration files at `/etc/rt-5gms/af-sync.conf` and `/etc/rt-5gms/streams.json`. The utility will also write out the `m8.json` file to be distributed via the interface at reference point M8 to the 5GMSd-Aware Application running on the UE. + +### `/etc/rt-5gms/af-sync.conf` - `msaf-configuration` configuration file + +This file holds some configuration parameters for the `msaf-configuration` utility. + +```ini +[af-sync] +m5_authority = af.example.com:7777 +docroot = /var/cache/rt-5gms/as/docroots +default_docroot = /usr/share/nginx/html +``` + +**m5_authority**: This should be set to the M5 address to advertise to the UE via the M8 application data object (default: 127.0.0.23:7777). +**docroot**: This is the directory path to where the Application Server will configure the document roots for each domainNameAlias configured (default: /var/cache/rt-5gms/as/docroots). +**default_docroot**: This is the directory path to the document root for the fallback virtual host offered by the Application Server (default: /usr/share/nginx/html). + +The defaults for *docroot* and *default_docroot* should not need to be set if the Application Server is running on the same host. These may need to be changed to network filesystem shares, shared with the 5GMSd Application Server, if the AS runs on a different host. + +The *m5_authority* should be set the the external hostname and port that the Application Function M5 interface can be found at. + +### `/etc/rt-5gms/streams.json` - Configuration of media streams to synchronise with the Application Function + +This is a JSON file which contains the information required to configure the Provisioning Sessions and Content Hosting Configurations on the 5GMSd Application Function. + +An example of this file would be: +```json +{ + "aspId": "The ASP ID to use, can be omitted", + "appId": "The external application id to use for all provisioning sessions", + "streams": { + "stream-id-1": { + "name": "Abc123 media", + "ingestURL": "https://media.example.com/media_assets/abc123/", + "distributionConfigurations": [ + { + "domainNameAlias": "as.exmaple.com", + "entryPoint": { + "relativePath": "manifest.mpd", + "contentType": "application/dash+xml", + "profiles": ["urn:mpeg:dash:profile:isoff-on-demand:2011"] + } + }, + { + "domainNameAlias": "as.exmaple.com", + "entryPoint": { + "relativePath": "manifest.m3u8", + "contentType": "application/vnd.apple.mpegurl" + } + } + ], + "consumptionReporting": { + "reportingInterval": 30, + "samplePercentage": 50.00, + "locationReporting": true, + "accessReporting": true + }, + "policies": [ + { + "externalReference": "pol-ext-1", + "applicationSessionContext": { + "sliceInfo": { "sst": 1, "sd": "000001" }, + "dnn": "internet" + }, + "qoSSpecification": { + "qosReference": "qosRef1", + "maxAuthBtrUl": "10 Mbps", + "maxAuthBtrDl": "1 Gbps", + "defPacketLossRateUl": 0, + "defPacketLossRateDl": 5 + }, + "chargingSpecification": { + "sponId": "sponsorIdentity1", + "sponStatus": "SPONSOR_ENABLED", + "gpsi": [ + "msimsi-447000123456", + "msimsi-447000654321" + ] + } + }, + { + "externalReference": "pol-ext-2", + "qoSSpecification": { + "maxAuthBtrUl": "100 Mbps", + "maxAuthBtrDl": "2 Gbps" + } + } + ] + }, + "stream-id-2": { + "name": "VOD service", + "ingestURL": "https://media.example.com/media_assets/", + "distributionConfigurations": [ + { + "domainNameAlias": "as.exmaple.com" + }, + { + "domainNameAlias": "as.exmaple.com", + "certificateId": "cert1" + } + ] + } + }, + "vodMedia": [ + { + "name": "Def456 VOD Media", + "stream": "stream_id-2", + "entryPoints": [ + { + "relativePath": "def456/manifest.mpd", + "contentType": "application/dash+xml", + "profiles": ["urn:mpeg:dash:profile:isoff-live:2011"] + }, + { + "relativePath": "def456/manifest.m3u8", + "contentType": "application/vnd.apple.mpegurl" + } + ] + }, + { + "name": "Ghi789 VOD Media", + "stream": "stream_id-2", + "entryPoints": [ + { + "relativePath": "ghi789/manifest.mpd", + "contentType": "application/dash+xml", + "profiles": ["urn:mpeg:dash:profile:isoff-live:2011"] + }, + { + "relativePath": "ghi789/manifest.m3u8", + "contentType": "application/vnd.apple.mpegurl" + } + ] + } + ] +} +``` + +The format is a JSON object which has the following fields: +- **aspID** - The Application Service Provider ID to provide when creating Provisioning Sessions. +- **appID** - The external application ID to use when creating Provisioning Sessions. +- **streams** - A description of the streams to configure, each in its own Provisioning Session. + - Each stream is identified in the configuration file by a unique identifier so that it may be referenced in the *vodMedia* field. + - The value for each stream contains the following fields: + - **name** - The name of the stream that will be configured in the ContentHostingConfiguration + - **ingestURL** - The base URL for media ingest from the media origin. + - **distributionConfigurations** - The array of distribution configurations that can appear in the ContentHostingConfiguration. + - See TS 26.512 for details of the format for this field. + - Any **certificateId** fields given in a distribution configuration will cause a certificate to be generated and the real certificate id will be substituted. Where the same certificate id is used for multiple entries in the *distributionConfigurations*, the same real certificate id will be substitued and that certificate only generated once. + - If an **entryPoint** field appears in any distribution configuration, then the M8 data file will contain an entry for this media and will use the *name* field for the stream as the media name and will only the include the Provisioning Session ID. The UE will be expected to consult the M5 interface for the entry point via the Service Access Information. + - If there are no *entryPoint*s then it is expected that the stream will be referenced from the *vodMedia* array in this configuration file. + - **consumptionReporting** - The optional consumption reporting configuration for the provisioning session. + - See TS 26.512 for details of this configuration. + - If this item is present then consumption reporting will be configured for the provisioning session. + - If this is an empty structure then consumption reporting is enabled for all clients using a single report at the end of the media playback. + - If the **reportingInterval** is given then the client will send a consumption report every **reportingInterval** seconds. + - If the **samplePercentage** is given this represents the percentage probability that a client will send consumption reports. At the start of the session the client determines a random number between 0 and 100 and if the value is less than or equal to this field value then the client will send reports for the session. If this field is not given then all clients will send reports. + - If the **locationReporting** field is present and is `true` then consumption reports will include UE location information. + - If the **accessReporting** field is present and is `true` then consumption reports will contain access information too. + - **policies** - The optional list of dynamic policy templates available for this stream. + - See TS 26.512 for details of PolicyTemplate configurations. + - If this item is present and has at least one entry then dynamic policies will be advertised to the clients for the provisioning session. + - Each object in the list must have an `externalReference` property, all other properties are optional. +- **vodMedia** - Array of media asset objects to advertise directly in the `m8.json` M8 interface data file. + - Each entry will create a media entry in the M8 data file which will have 1 or more entry points associated with it. + - Each media asset in the array contains the following fields: + - **name** - The name to use for the media name in the M8 data file media entry. + - **stream** - A reference to a stream defined in the *streams* map in this configuration file. + - This is used to find the provisioning session id and distribution points for the stream. + - **entryPoints** - An array of relative entry points for the media assets. + - Each entry takes the same format as the *streams.distributionConfigurations.entryPoint*. + - Entry points for the media asset written to the M8 data file are absolute URLs and are derived from the *entryPoints* fields combined with each entry in *stream.distributionConfigurations*. + +In the example above there are two Provisioning Sessions which will be configured in the running Application Function. + +The first, *stream-id-1*, is for a single media asset. This will result in the the M8 data file containing an entry for the "Abc123 media" media asset which has no entry points, just a provisioning session Id. The M5 Service Access Information for this provisioning session will contain the two entry points defined, one for the DASH stream and one for the HLS stream both available using the HTTP protocol (no "certificateId" present). This stream will also request that half the clients submit consumption reports every 30 seconds which contain both location and access information. There will also be two dynamic policies advertised as available for use with this stream. + +The second, *stream-id-2*, will create a Provisioning Session which acts as a VOD entry point for multiple streams advertised via M8. There are two distribution points for this provisioning session, one HTTP and the other HTTPS. The M5 Service Access Information will have no entryPoints listed. The M8 data file entries using this provisioning session id will be derived from the *vodMedia* entries which reference stream *stream-id-2*. + +The *vodMedia* array contains two media assets which will be listed in the M8 data file using the *name* from the *vodMedia* entry and the Provisioning session Id of the provisioning session created for *stream-id-2* in the *streams* section above. Each entry will list the entryPoints for each of the *entryPoints* defined for the media asset combined with each of the distribution points from the provisioning session for *stream-id-2*. Therefore, in the M8 data file, there will be 4 entry points for "Def456 VOD Media": DASH over HTTP, DASH over HTTPS, HLS over HTTP and HLS over HTTPS; and a similar 4 entry points for the "Ghi789 VOD Media". + +The M8 data file generated from the example above will have 3 media assets, the first for "Abc123" will just have a provisioning session id and the other two, "Def456" and "Ghi789", will both contain the same provisioning session id but will have 4 different entry points each for the combinations of DASH/HLS and HTTP/HTTPS. diff --git a/pages/5g-media-streaming/testing/testing-AS.md b/pages/5g-media-streaming/testing/testing-AS.md new file mode 100644 index 00000000..d3529d3b --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-AS.md @@ -0,0 +1,231 @@ +--- +layout: default +title: Testing the 5GMS AS +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 3 +--- + +# Developing and Testing the 5GMSd Application Server + +While the instructions in the main project [README](https://github.com/5G-MAG/rt-5gms-application-server#readme) tell you how to install the 5GMSd Application Server as a system-wide application, during development it is usually more appropriate to have one or more local clones of the repository that are being used for development and testing. This page provides details of one suggested way to arrange your development environment to ensure separation from the main system during development and testing. + +# Prerequisites + +There are some packages that will need to be installed system wide that the build and install system relies on. These prerequisite packages are: +- **Commands** + - Git + - Java + - Python 3 + - Wget +- **Python 3 modules** + - pip + - venv + +These can usually be installed as system packages, for example: +**Debian/Ubuntu Linux and derivatives** +```bash +sudo apt -y install git default-jdk python3 wget python3-pip python3-venv +``` + +**RHEL/CentOS/Fedora/Rocky** +```bash +sudo dnf -y install git java-latest-openjdk python3 wget python3-pip python3-venv +``` + +# Checking out the project code + +Since this will be used for development and testing, the instructions here will show you how to check out the latest development branch. + +## Checkout for development + +1. **Create a fork** + 1. Login to GitHub ([create a GitHub account](https://github.com/join) and [set an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) if you haven't already done so). + 1. On the main [GitHub project page](https://github.com/5G-MAG/rt-5gms-application-server) click on the "Fork" label in the top right of the page, then untick "Copy the `main` branch only" on the page that appears and select the "Create fork" button. + 1. On your new fork page select the `Settings` option just below the main repository title. Then select "Branches" under the "Code and automation" topic from the sections on the left, and edit the "Default branch" to change it to `development`. + 1. Clone the repository + ```bash + cd + git clone --recurse-submodules git@github.com:/rt-5gms-application-server.git + ``` + Where `` is the username of your GitHub login. + +## Checkout for testing only + +1. **Clone the 5G-MAG repository** + ```bash + cd + git clone -b development --recurse-submodules https://github.com/5G-MAG/rt-5gms-application-server.git + ``` + +# Creating the virtual Python environment + +By using a Python virtual environment you can use upgraded versions of existing system Python modules and automatically install project module dependencies without having to install or upgrade modules system wide. + +1. Create the virtual Python environment + + ```bash + cd ~/rt-5gms-application-server + python3 -m venv venv + ``` + +1. Update base modules and test script dependencies + + ```bash + cd ~/rt-5gms-application-server + venv/bin/python3 -m pip install --upgrade pip build setuptools docopt PyYAML + ``` + +# Build and install the 5GMSd Application Server + +```bash +cd ~/rt-5gms-application-server +venv/bin/python3 -m pip install . +``` + +# Create a local-user friendly configuration + +Save these configuration file contents as `~/rt-5gms-application-server/local-dev.conf`: +```ini +### Defaults for the 5G-MAG Reference Tools: 5GMSd applications +[DEFAULT] +log_dir = /tmp/rt-5gms-as/logs +run_dir = /tmp/rt-5gms-as + +### 5GMSd Application Server specific configurations +[5gms_as] +log_level = debug +cache_dir = /tmp/rt-5gms-as/cache +certificates_cache = /tmp/rt-5gms-as/certificates +http_port = 8080 +https_port = 8443 +#m3_listen = localhost +#m3_port = 7777 +#access_log = %(log_dir)s/application-server-access.log +#error_log = %(log_dir)s/application-server-error.log +#pid_path = %(run_dir)s/application-server.pid + +### 5GMSd Application Server nginx specific configuration +[5gms_as.nginx] +root_temp = /tmp/rt-5gms-as +#client_body_temp = %(root_temp)s/client-body-tmp +#proxy_temp = %(root_temp)s/proxy-tmp +#fastcgi_temp = %(root_temp)s/fastcgi-tmp +#uwsgi_temp = %(root_temp)s/uwsgi-tmp +#scgi_temp = %(root_temp)s/scgi-tmp +#pid_path = %(root_temp)s/5gms-as-nginx.pid +``` + +Using this configuration will: +- Place all 5GMSd Application Server cache directories and other temporary files and logs under the `/tmp/rt-5gms-as` directory for testing. +- Change the default ports used for the 5GMSd distribution service at reference point M4d. Note that this means that all URLs output by the 5GMSd Application Function with respect to M4d will need to be manually modified to insert the new port numbers before use, e.g. if the AF publishes a URL starting `http://your.hostname/...` you will need to change that to `http://your.hostname:8080/...` in order to use the URL. This is necessary as the default ports of 80 and 443 are not available to normal unprivileged users. A normal user has to use ports with a number greater than 1024. +- Turn on `debug` level output from the 5GMSd Application Server in order to better see what it happening. +- Some settings above are commented out but may be useful while testing and so have been left in with their default values and prefixed with `#` to comment them out. If you wish to change one then remove the `#` and change the value to your desired setting. + +# Running the installed 5GMSd Application server + +To run the version of the 5GMSd Application Server installed in the virtual environment with the `local-dev.conf` configuration (above), use: + +```bash +cd ~/rt-5gms-application-server +PATH="/usr/local/openresty/nginx/sbin:$PATH" venv/bin/5gms-application-server -c local-dev.conf +``` + +# Runtime configuration + +The 5GMSd Application Server is configured at run-time for distribution of media via the interface at reference point M3. This is usually done by the [5GMSd Application Function](https://github.com/5G-MAG/rt-5gms-application-function), but this project also contains a simple M3 client that can be used to push run-time configuration for testing. + +## M3 test client + +This client script provides a simple command line interface to issue M3 API calls and see the result from the response. + +The script can be run as: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -h|{ [...]} +``` + +If the default values for `m3_listen` and `m3_port` are used in the configuration file the `` will be `localhost:7777`. + +To see the command line help use: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -h +``` + +## M3 Certificates API + +### List known certificates + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 +``` + +### Add a new certificate + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 add testcert1 tests/examples/certificate-1.pem +``` + +### Update an existing certificate + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 update testcert1 tests/examples/certificate-1.pem +``` + +### Delete a certificate + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -c localhost:7777 delete testcert1 +``` + +## M3 ContentHostingConfiguration API + +### List known ContentHostingConfigurations + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 +``` + +### Add a new ContentHostingConfiguration + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 add prov-sess-1 tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_http_and_https.json +``` + +### Update an existing ContentHostingConfiguration + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 update prov-sess-1 tests/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json +``` + +### Delete a ContentHostingConfiguration + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 delete prov-sess-1 +``` + +### Purge all cached objects for a ContentHostingConfiguration + +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 purge prov-sess-1 +``` + +### Purge cached objects using a path regex for a ContentHostingConfiguration + +For example to purge all DASH manifests: +```bash +cd ~/rt-5gms-application-server +tests/m3_client_cli.py -H localhost:7777 purge prov-sess-1 '\.mpd$' +``` + diff --git a/pages/5g-media-streaming/testing/testing-m1-v120.md b/pages/5g-media-streaming/testing/testing-m1-v120.md new file mode 100644 index 00000000..1133934c --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m1-v120.md @@ -0,0 +1,642 @@ +--- +layout: default +title: Testing M1 AF v1.2.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 6 +--- + +# Testing: M1 Interface (5GMSd Application Function v1.2.x) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +These tests require a [5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server) to be running. Please follow +the instructions to [build, install and run the 5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server#readme) as a system service or the [instructions to run the AS as a local user](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) for a temporary installation for testing. + +## Test Provisioning Sessions + +This will test the ability of the Application Function to allocate and retrieve information about provisioning session upon request by an Application Provider. + +### Create provisioning sessions + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list a single provisioning session. + +1. Create a second Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Sessions: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list the two provisioning sessions. + +### Get details for a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session with Content Hosting Configuration + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session details: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will list the provisioning session showing the Content Hosting Configuration attached to it. + + For example: + + ``` + 1c961622-c803-41ed-83c5-e304b44dbd7e: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-1c961622-c803-41ed-83c5-e304b44dbd7e/ + Canonical Domain Name: localhost + ``` + +### Delete a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list a single provisioning session. + +1. Delete the Provisioning Session by Id: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the earlier step. + + For example: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream -p 1c961622-c803-41ed-83c5-e304b44dbd7e + ``` + +1. Check the Provisioning Session is deleted: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + There should be no provisioning sessions listed. + +1. Create a single Provisioning Session with a stream identifier: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Test Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + +1. Delete the Provisioning Session by ingest URL and entry point path: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session is deleted: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + There should be no provisioning sessions listed. + +## Server Certificates + +### Create Server Certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Create a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should show a provisioning session with a single certificate where the subject and issuer of the certificate are + identical. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that for provisioning session 40b75340-c8a3-41ed-9d6e-cbf27240da7a there is a certificate with id + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a lasting for 90 days from 22nd Mar 2023. The "Subject" and "Issuer" both have the same + designated name ("C=GB,L=London,CN=localhost") and key hash, showing that this is a self signed certificate. The + "Subject Alternative Names" contains one "DNS" entry for the canonical name of the 5GMSd Application Server. + +1. Create a certificate with a domain name: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} -d as.example.com + ``` + + Since a domain name was requested, the `m1-session` tool will request a CSR from the 5GMSd Application Function and sign it + itself. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should now show an extra certificate on the provisioning session. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that there is now a second certificate (8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a) issued by + "5G-MAG Reference Tools Local CA" and the Subject Common Name is the domain name alias used with the `-d` command line option + when the certificate was created. The canonical domain name of the 5GMSd Application Server is the second Subject Alternative + Name. These certificates last for 30 days by default. + +1. Reserve a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} --csr + ``` + + The output includes the new certificate id and a CSR in PEM format. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should now show a third certificate id but the certificate detail says "Certificate not yet uploaded". + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a: + Certificate not yet uploaded + ContentHostingConfiguration: + Not defined + ``` + + This shows that the 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a certificate is waiting for a signed certificate to be uploaded. + +### Output certificate details + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Create a certificate + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Display the details of the certificate + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4 and + `${certificate_id}` is the certificate id of the certificate created in the previous step. + + This will display the certificate details. + + For example: + + ``` + Certificate details for d921a6e2-c977-41ed-ae8f-4f7bb018a30b: + Serial = 570812267048735513617861647966053937458169779179 + Not before = 2023-03-23 12:40:10+00:00 + Not after = 2023-06-21 12:40:10+00:00 + Subject = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Issuer = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Subject Alternative Names: + DNS:localhost + ``` + +1. Display the public certificate PEM data + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} -r + ``` + + The `-r` flag causes the command to display the "raw" output which is the PEM data for the certificate. + + For example: + + ``` + -----BEGIN CERTIFICATE----- + MIIDWzCCAkOgAwIBAgIUY/wbeD1YUiEeBPLpxf8ldkkEE+swDQYJKoZIhvcNAQEL + BQAwMjELMAkGA1UEBhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9j + YWxob3N0MB4XDTIzMDMyMzEyNDAxMFoXDTIzMDYyMTEyNDAxMFowMjELMAkGA1UE + BhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjAN + BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0bftLTaaXXpW1qIDHYTTmeIGvupy + G/dQpK5Ko9mW9IEcb+wfn2fX8SMHGA7O8TvpqUGEmyoBXIuIFmmeR+w5xQRcKkyi + NGhIhnUIfOqaevh4MCX/8Ius9NOjF0bz+aWtwOCmWKkNvknRMzClAeVRJm6g+U6m + IH30TE5H3ItiYxk63MNvuYeqIEK2rEKu69jWvTFkV1Wzd+5rH3ZC9qrt4uryUqAZ + X6XPx5AkQzbnBRQooDJzhqKgW+7YFWFtwi6WX8poGwx4RuruxYRLEBDfxRCE/1k6 + ALP3IktsVp7rFqwOt0LRNH1+MLly/MIOEA+NjnaIReG3/6Kt7oAqiDCBpQIDAQAB + o2kwZzAdBgNVHQ4EFgQU6WH9WjEM7cCwzCkNKYmu7vklicowHwYDVR0jBBgwFoAU + 6WH9WjEM7cCwzCkNKYmu7vklicowDwYDVR0TAQH/BAUwAwEB/zAUBgNVHREEDTAL + gglsb2NhbGhvc3QwDQYJKoZIhvcNAQELBQADggEBAIAELtWEMwzoXnaWRn74JngW + 3DF5IUtdFOiEKPWzdju+RleUsQHm5hsbPxpAz/MDVKIQQBGrJNMNpMtJ1VNlAsJ1 + 7gndSkSFf0zw7+DxgKYiwNj7tbBU8yTW+qVyUJh6XUxOHlaLjXzct4jw/NgjrjRZ + YuwXKCebRf+DUtQGt87rSib+GVpI//XBweyd8D0vFnGPRU9yyAvuqUdfu7enGFMr + qyBBqTqrTgX9o852lrMnWbc+g+of90Ym9HkVpifmc12jZSJlfS4cykvwnRqwPC9f + YnNABBMDJwJOM8g69OIRw+67O01ZulRzCvSaSbBEG6xC08XAD7BJn9CPIMypHdw= + -----END CERTIFICATE----- + ``` + +### Upload a public certificate + +**TODO:** Test where we reserve a certificate and the fetch CSR for the new certificate, sign it, and upload the result. + +## Content Protocol Discovery + +### List the Content Protocols available + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. List the Content Protocols for the Provisioning Session + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session protocols -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + + The available protocols will be listed. + + For example: + + ``` + Protocols for 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Downlink: + urn:3gpp:5gms:content-protocol:http-pull-ingest + No uplink capability + No geo-fencing capability + ``` + +## Content Hosting Provisioning + +### Add a Content Hosting Configuration without certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Create the hosting configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-stream -p ${provisioning_session_id} ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the provisioning session configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + 2ef78712-c9a0-41ed-ac37-f9964ab0d12a: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-2ef78712-c9a0-41ed-ac37-f9964ab0d12a/ + Canonical Domain Name: localhost + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above can also be done using: +``` +~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` + +### Add a Content Hosting Configuration which uses an existing certificate + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Create a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Generate a ContentHostingConfiguration using the certificate: + + ```bash + sed "s/@certificate-id@/${certificate_id}/g" ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json.tmpl > chc.json + ``` + + Where `${certificate_id}` is the certificate id of the certificate created in the previous step. + +1. Create the hosting configuration using the generated ContentHostingConfiguration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-stream -p ${provisioning_session_id} chc.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4. + +1. Check the provisioning session configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + ed5079d6-c9a4-41ed-b2ad-41232d457177: + Certificates: + fbd05ddc-c9a4-41ed-b2ad-41232d457177: + Serial = 186484472102456711697672477872825927418601662068 + Not before = 2023-03-23 18:03:15+00:00 + Not after = 2023-06-21 18:03:15+00:00 + Subject = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Issuer = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: https://localhost/m4d/provisioning-session-ed5079d6-c9a4-41ed-b2ad-41232d457177/ + Canonical Domain Name: localhost + Certificate: fbd05ddc-c9a4-41ed-b2ad-41232d457177 + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above configuration with the `m1-session` tool can also be done using this single command instead: +``` +~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' --ssl-only 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` diff --git a/pages/5g-media-streaming/testing/testing-m1-v130.md b/pages/5g-media-streaming/testing/testing-m1-v130.md new file mode 100644 index 00000000..38f9a333 --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m1-v130.md @@ -0,0 +1,859 @@ +--- +layout: default +title: Testing M1 AF v1.3.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 7 +--- + +# Testing: M1 Interface (5GMSd Application Function v1.3.0 to v1.4.0) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Testing + +These tests require a [5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server) to be running. Please follow +the instructions to [build, install and run the 5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server#readme) as a system service or the [instructions to run the AS as a local user](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) for a temporary installation for testing. + +## Test Provisioning Sessions + +This will test the ability of the Application Function to allocate and retrieve information about provisioning session upon request by an Application Provider. + +### Create provisioning sessions + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list a single provisioning session. + +1. Create a second Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Sessions: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list the two provisioning sessions. + +### Get details for a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session with Content Hosting Configuration + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session details: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will list the provisioning session showing the Content Hosting Configuration attached to it. + + For example: + + ``` + 39f4f698-daa0-41ed-862b-c1f4c44bccf3: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-39f4f698-daa0-41ed-862b-c1f4c44bccf3/ + Canonical Domain Name: localhost + Entry point: + Relative Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Content Type: application/dash+xml + ``` + +### Delete a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + This should list a single provisioning session. + +1. Delete the Provisioning Session by Id: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the earlier step. + + For example: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream -p 1c961622-c803-41ed-83c5-e304b44dbd7e + ``` + +1. Check the Provisioning Session is deleted: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + There should be no provisioning sessions listed. + +1. Create a single Provisioning Session with a stream identifier: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Test Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + +1. Delete the Provisioning Session by ingest URL and entry point path: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-stream 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + + **Note:** The entry point (last command line parameter) can be any one of the entry point relative paths present in a + distribution configuration for the content hosting configuration of a provisioning session. + +1. Check the Provisioning Session is deleted: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list + ``` + + There should be no provisioning sessions listed. + +### Create a hosting configuration with multiple entry points + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session with Content Hosting Configuration containing multiple entry points + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/' 'manifest(format=mpd-time-csf)' 'manifest(format=m3u8-aapl-v3)' + ``` + +1. Check the Provisioning Session details: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will list the provisioning session showing the Content Hosting Configuration attached to it. + + For example: + + ``` + 74f4c492-dacf-41ed-87fe-93ba2b9b790a: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=mpd-time-csf) + Content Type: application/dash+xml + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=m3u8-aapl-v3) + Content Type: application/vnd.apple.mpegurl + ``` + + The output shows that the ContentHostingConfiguration for Provisioning Session 74f4c492-dacf-41ed-87fe-93ba2b9b790a has two + distribution configurations. There is one distribution configuration for DASH and one for HLS. + +### Create a hosting configuration from a JSON file + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Upload the ContentHostingConfiguration JSON file: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-stream -p ${provisioning_session_id} ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json + ``` + + Where `${provisioning_session_id}` is the Provisioning Session Id reported by the previous step. + + For this step one of the example configuration files from the `~/rt-5gms-application-function/examples` directory was used, but any valid ContentHostingConfiguration JSON file can be used. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should show a provisioning session with the contents of the JSON file used as the ContentHostingConfiguration. + + For example: + + ``` + 74f4c492-dacf-41ed-87fe-93ba2b9b790a: + Certificates: + ContentHostingConfiguration: + Name: AMP Demo Stream: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=mpd-time-csf) + Content Type: application/dash+xml + Profiles: + - urn:mpeg:dash:profile:isoff-live:2011 + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=m3u8-aapl-v3) + Content Type: application/vnd.apple.mpegurl + ``` + + This also tests the use of profile lists in the distribution entry points. + +## Server Certificates + +### Create Server Certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should show a provisioning session with a single certificate where the subject and issuer of the certificate are + identical. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that for provisioning session 40b75340-c8a3-41ed-9d6e-cbf27240da7a there is a certificate with id + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a lasting for 90 days from 22nd Mar 2023. The "Subject" and "Issuer" both have the same + designated name ("C=GB,L=London,CN=localhost") and key hash, showing that this is a self signed certificate. The + "Subject Alternative Names" contains one "DNS" entry for the canonical name of the 5GMSd Application Server. + +1. Create a certificate with a domain name: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} -d as.example.com + ``` + + Since a domain name was requested, the `m1-session` tool will request a CSR from the 5GMSd Application Function and sign it + itself. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should now show an extra certificate on the provisioning session. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that there is now a second certificate (8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a) issued by + "5G-MAG Reference Tools Local CA" and the Subject Common Name is the domain name alias used with the `-d` command line option + when the certificate was created. The canonical domain name of the 5GMSd Application Server is the second Subject Alternative + Name. These certificates last for 30 days by default. + +1. Reserve a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} --csr + ``` + + The output includes the new certificate id and a CSR in PEM format. + +1. Check the Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + The output should now show a third certificate id but the certificate detail says "Certificate not yet uploaded". + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a: + Certificate not yet uploaded + ContentHostingConfiguration: + Not defined + ``` + + This shows that the 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a certificate is waiting for a signed certificate to be uploaded. + +### Output certificate details + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + + **Hint:** Set the shell variable `certificate_id` to the returned certificate id for use in later commands. + +1. Display the details of the certificate + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4 and + `${certificate_id}` is the certificate id of the certificate created in the previous step. + + This will display the certificate details. + + For example: + + ``` + Certificate details for d921a6e2-c977-41ed-ae8f-4f7bb018a30b: + Serial = 570812267048735513617861647966053937458169779179 + Not before = 2023-03-23 12:40:10+00:00 + Not after = 2023-06-21 12:40:10+00:00 + Subject = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Issuer = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Subject Alternative Names: + DNS:localhost + ``` + +1. Display the public certificate PEM data + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} -r + ``` + + The `-r` flag causes the command to display the "raw" output which is the PEM data for the certificate. + + For example: + + ``` + -----BEGIN CERTIFICATE----- + MIIDWzCCAkOgAwIBAgIUY/wbeD1YUiEeBPLpxf8ldkkEE+swDQYJKoZIhvcNAQEL + BQAwMjELMAkGA1UEBhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9j + YWxob3N0MB4XDTIzMDMyMzEyNDAxMFoXDTIzMDYyMTEyNDAxMFowMjELMAkGA1UE + BhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjAN + BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0bftLTaaXXpW1qIDHYTTmeIGvupy + G/dQpK5Ko9mW9IEcb+wfn2fX8SMHGA7O8TvpqUGEmyoBXIuIFmmeR+w5xQRcKkyi + NGhIhnUIfOqaevh4MCX/8Ius9NOjF0bz+aWtwOCmWKkNvknRMzClAeVRJm6g+U6m + IH30TE5H3ItiYxk63MNvuYeqIEK2rEKu69jWvTFkV1Wzd+5rH3ZC9qrt4uryUqAZ + X6XPx5AkQzbnBRQooDJzhqKgW+7YFWFtwi6WX8poGwx4RuruxYRLEBDfxRCE/1k6 + ALP3IktsVp7rFqwOt0LRNH1+MLly/MIOEA+NjnaIReG3/6Kt7oAqiDCBpQIDAQAB + o2kwZzAdBgNVHQ4EFgQU6WH9WjEM7cCwzCkNKYmu7vklicowHwYDVR0jBBgwFoAU + 6WH9WjEM7cCwzCkNKYmu7vklicowDwYDVR0TAQH/BAUwAwEB/zAUBgNVHREEDTAL + gglsb2NhbGhvc3QwDQYJKoZIhvcNAQELBQADggEBAIAELtWEMwzoXnaWRn74JngW + 3DF5IUtdFOiEKPWzdju+RleUsQHm5hsbPxpAz/MDVKIQQBGrJNMNpMtJ1VNlAsJ1 + 7gndSkSFf0zw7+DxgKYiwNj7tbBU8yTW+qVyUJh6XUxOHlaLjXzct4jw/NgjrjRZ + YuwXKCebRf+DUtQGt87rSib+GVpI//XBweyd8D0vFnGPRU9yyAvuqUdfu7enGFMr + qyBBqTqrTgX9o852lrMnWbc+g+of90Ym9HkVpifmc12jZSJlfS4cykvwnRqwPC9f + YnNABBMDJwJOM8g69OIRw+67O01ZulRzCvSaSbBEG6xC08XAD7BJn9CPIMypHdw= + -----END CERTIFICATE----- + ``` + +### Upload a public certificate + +**TODO:** Test where we reserve a certificate and the fetch CSR for the new certificate, sign it, and upload the result. + +## Content Protocol Discovery + +### List the Content Protocols available + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. List the Content Protocols for the Provisioning Session + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session protocols -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + + The available protocols will be listed. + + For example: + + ``` + Protocols for 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Downlink: + urn:3gpp:5gms:content-protocol:http-pull-ingest + No uplink capability + No geo-fencing capability + ``` + +## Content Hosting Provisioning + +### Add a Content Hosting Configuration without certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create the hosting configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-stream -p ${provisioning_session_id} ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the provisioning session configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + 2ef78712-c9a0-41ed-ac37-f9964ab0d12a: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-2ef78712-c9a0-41ed-ac37-f9964ab0d12a/ + Canonical Domain Name: localhost + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above can also be done using: +``` +~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` + +### Add a Content Hosting Configuration which uses an existing certificate + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Generate a ContentHostingConfiguration using the certificate: + + ```bash + sed "s/@certificate-id@/${certificate_id}/g" ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json.tmpl > chc.json + ``` + + Where `${certificate_id}` is the certificate id of the certificate created in the previous step. + +1. Create the hosting configuration using the generated ContentHostingConfiguration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-stream -p ${provisioning_session_id} chc.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4. + +1. Check the provisioning session configuration: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + ed5079d6-c9a4-41ed-b2ad-41232d457177: + Certificates: + fbd05ddc-c9a4-41ed-b2ad-41232d457177: + Serial = 186484472102456711697672477872825927418601662068 + Not before = 2023-03-23 18:03:15+00:00 + Not after = 2023-06-21 18:03:15+00:00 + Subject = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Issuer = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: https://localhost/m4d/provisioning-session-ed5079d6-c9a4-41ed-b2ad-41232d457177/ + Canonical Domain Name: localhost + Certificate: fbd05ddc-c9a4-41ed-b2ad-41232d457177 + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above configuration with the `m1-session` tool can also be done using this single command instead: +``` +~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' --ssl-only 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` + +## Consumption Reporting (v1.4.0 and later) + +### Add a Consumption Reporting Configuration + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a Consumption Reporting Configuration for the Provisioning Session + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-consumption-reporting -p ${provisioning_session_id} --interval 15 --sample-percentage 66.66 --location-reporting --access-reporting + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4. + + This will set consumption reporting to every 15 seconds for 66.66% of clients and reports should include Location and Access reporting. + + All Consumption Reporting parameters are optional so doing the following: + ```bash + ~/rt-5gms-application-function/install/bin/m1-session set-consumption-reporting -p ${provisioning_session_id} + ``` + ...will request all clients send a single Consumption Report at the end of the media without Location or Access reports (the defaults for consumption reporting). + +### Show current Consumption Reporting Configuration + +1. Display the current Consumption Reporting Configuration for a Provisioning Session + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to view. + +### Remove the Consumption Reporting Configuration + +1. Remove Consumption Reporting from a Provisioning Session + ```bash + ~/rt-5gms-application-function/install/bin/m1-session del-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to remove consumption reporting from. + +1. Display the current Consumption Reporting Configuration for the Provisioning Session to check it has gone + ```bash + ~/rt-5gms-application-function/install/bin/m1-session show-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to view. + + This will report no Consumption Reporting Configuration is present. diff --git a/pages/5g-media-streaming/testing/testing-m1-v141.md b/pages/5g-media-streaming/testing/testing-m1-v141.md new file mode 100644 index 00000000..2942fd37 --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m1-v141.md @@ -0,0 +1,859 @@ +--- +layout: default +title: Testing M1 AF v1.4.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 8 +--- + +# Testing: M1 Interface (5GMSd Application Function v1.4.1 and later) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Testing + +These tests require a [5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server) to be running. Please follow +the instructions to [build, install and run the 5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server#readme) as a system service or the [instructions to run the AS as a local user](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) for a temporary installation for testing. + +## Test Provisioning Sessions + +This will test the ability of the Application Function to allocate and retrieve information about provisioning session upon request by an Application Provider. + +### Create provisioning sessions + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Session: + + ```bash + m1-session list + ``` + + This should list a single provisioning session. + +1. Create a second Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + +1. Check the Provisioning Sessions: + + ```bash + m1-session list + ``` + + This should list the two provisioning sessions. + +### Get details for a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session with Content Hosting Configuration + + ```bash + m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session details: + + ```bash + m1-session list -v + ``` + + This will list the provisioning session showing the Content Hosting Configuration attached to it. + + For example: + + ``` + 39f4f698-daa0-41ed-862b-c1f4c44bccf3: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-39f4f698-daa0-41ed-862b-c1f4c44bccf3/ + Canonical Domain Name: localhost + Entry point: + Relative Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Content Type: application/dash+xml + ``` + +### Delete a provisioning session + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Check the Provisioning Session: + + ```bash + m1-session list + ``` + + This should list a single provisioning session. + +1. Delete the Provisioning Session by Id: + + ```bash + m1-session del-stream -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the earlier step. + + For example: + + ```bash + m1-session del-stream -p 1c961622-c803-41ed-83c5-e304b44dbd7e + ``` + +1. Check the Provisioning Session is deleted: + + ```bash + m1-session list + ``` + + There should be no provisioning sessions listed. + +1. Create a single Provisioning Session with a stream identifier: + + ```bash + m1-session new-stream -e MyAppId -a MyASPId -n 'Test Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Check the Provisioning Session: + + ```bash + m1-session list -v + ``` + +1. Delete the Provisioning Session by ingest URL and entry point path: + + ```bash + m1-session del-stream 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + + **Note:** The entry point (last command line parameter) can be any one of the entry point relative paths present in a + distribution configuration for the content hosting configuration of a provisioning session. + +1. Check the Provisioning Session is deleted: + + ```bash + m1-session list + ``` + + There should be no provisioning sessions listed. + +### Create a hosting configuration with multiple entry points + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session with Content Hosting Configuration containing multiple entry points + + ```bash + m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/' 'manifest(format=mpd-time-csf)' 'manifest(format=m3u8-aapl-v3)' + ``` + +1. Check the Provisioning Session details: + + ```bash + m1-session list -v + ``` + + This will list the provisioning session showing the Content Hosting Configuration attached to it. + + For example: + + ``` + 74f4c492-dacf-41ed-87fe-93ba2b9b790a: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=mpd-time-csf) + Content Type: application/dash+xml + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=m3u8-aapl-v3) + Content Type: application/vnd.apple.mpegurl + ``` + + The output shows that the ContentHostingConfiguration for Provisioning Session 74f4c492-dacf-41ed-87fe-93ba2b9b790a has two + distribution configurations. There is one distribution configuration for DASH and one for HLS. + +### Create a hosting configuration from a JSON file + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Upload the ContentHostingConfiguration JSON file: + + ```bash + m1-session set-stream -p ${provisioning_session_id} ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json + ``` + + Where `${provisioning_session_id}` is the Provisioning Session Id reported by the previous step. + + For this step one of the example configuration files from the `~/rt-5gms-application-function/examples` directory was used, but any valid ContentHostingConfiguration JSON file can be used. + +1. Check the Provisioning Session: + + ```bash + m1-session list -v + ``` + + The output should show a provisioning session with the contents of the JSON file used as the ContentHostingConfiguration. + + For example: + + ``` + 74f4c492-dacf-41ed-87fe-93ba2b9b790a: + Certificates: + ContentHostingConfiguration: + Name: AMP Demo Stream: Big Buck Bunny + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + Pull Ingest?: True + URL: http://amssamples.streaming.mediaservices.windows.net/622b189f-ec39-43f2-93a2-201ac4e31ce1/BigBuckBunny.ism/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=mpd-time-csf) + Content Type: application/dash+xml + Profiles: + - urn:mpeg:dash:profile:isoff-live:2011 + - URL: http://localhost/m4d/provisioning-session-74f4c492-dacf-41ed-87fe-93ba2b9b790a/ + Canonical Domain Name: localhost + Entry point: + Relative Path: manifest(format=m3u8-aapl-v3) + Content Type: application/vnd.apple.mpegurl + ``` + + This also tests the use of profile lists in the distribution entry points. + +## Server Certificates + +### Create Server Certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate: + + ```bash + m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the Provisioning Session: + + ```bash + m1-session list -v + ``` + + The output should show a provisioning session with a single certificate where the subject and issuer of the certificate are + identical. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that for provisioning session 40b75340-c8a3-41ed-9d6e-cbf27240da7a there is a certificate with id + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a lasting for 90 days from 22nd Mar 2023. The "Subject" and "Issuer" both have the same + designated name ("C=GB,L=London,CN=localhost") and key hash, showing that this is a self signed certificate. The + "Subject Alternative Names" contains one "DNS" entry for the canonical name of the 5GMSd Application Server. + +1. Create a certificate with a domain name: + + ```bash + m1-session new-certificate -p ${provisioning_session_id} -d as.example.com + ``` + + Since a domain name was requested, the `m1-session` tool will request a CSR from the 5GMSd Application Function and sign it + itself. + +1. Check the Provisioning Session: + + ```bash + m1-session list -v + ``` + + The output should now show an extra certificate on the provisioning session. + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + ContentHostingConfiguration: + Not defined + ``` + + This shows that there is now a second certificate (8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a) issued by + "5G-MAG Reference Tools Local CA" and the Subject Common Name is the domain name alias used with the `-d` command line option + when the certificate was created. The canonical domain name of the 5GMSd Application Server is the second Subject Alternative + Name. These certificates last for 30 days by default. + +1. Reserve a certificate: + + ```bash + m1-session new-certificate -p ${provisioning_session_id} --csr + ``` + + The output includes the new certificate id and a CSR in PEM format. + +1. Check the Provisioning Session: + + ```bash + m1-session list -v + ``` + + The output should now show a third certificate id but the certificate detail says "Certificate not yet uploaded". + + For example: + + ``` + 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Certificates: + 4fff7e04-c8a3-41ed-9d6e-cbf27240da7a: + Serial = 723264618754945153424478507276304617300583059881 + Not before = 2023-03-22 11:18:46+00:00 + Not after = 2023-06-20 11:18:46+00:00 + Subject = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Issuer = C=GB,L=London,CN=localhost + key=C2:56:2C:A6:D7:B3:AE:C7:3A:2C:18:9D:5B:2A:EB:62:C0:7E:35:05 + Subject Alternative Names: + DNS:localhost + 8aa9e5ac-c8a9-41ed-9d6e-cbf27240da7a: + Serial = 1 + Not before = 2023-03-22 12:03:22+00:00 + Not after = 2023-04-21 12:03:22+00:00 + Subject = CN=as.example.com,O=5G-MAG + key=37:62:38:E1:D2:18:23:90:A9:12:2A:C7:EF:5F:7E:F8:91:3A:89:8F + Issuer = O=5G-MAG,CN=5G-MAG Reference Tools Local CA + key=B4:2F:13:EE:02:D0:34:75:C0:7B:9D:C7:67:6D:90:76:F5:A8:CC:EF + Subject Alternative Names: + DNS:as.example.com + DNS:localhost + 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a: + Certificate not yet uploaded + ContentHostingConfiguration: + Not defined + ``` + + This shows that the 2a118b8e-c8a7-41ed-9d6e-cbf27240da7a certificate is waiting for a signed certificate to be uploaded. + +### Output certificate details + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate + + ```bash + m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + + **Hint:** Set the shell variable `certificate_id` to the returned certificate id for use in later commands. + +1. Display the details of the certificate + + ```bash + m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4 and + `${certificate_id}` is the certificate id of the certificate created in the previous step. + + This will display the certificate details. + + For example: + + ``` + Certificate details for d921a6e2-c977-41ed-ae8f-4f7bb018a30b: + Serial = 570812267048735513617861647966053937458169779179 + Not before = 2023-03-23 12:40:10+00:00 + Not after = 2023-06-21 12:40:10+00:00 + Subject = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Issuer = C=GB,L=London,CN=localhost + key=E9:61:FD:5A:31:0C:ED:C0:B0:CC:29:0D:29:89:AE:EE:F9:25:89:CA + Subject Alternative Names: + DNS:localhost + ``` + +1. Display the public certificate PEM data + + ```bash + m1-session show-certificate -p ${provisioning_session_id} -c ${certificate_id} -r + ``` + + The `-r` flag causes the command to display the "raw" output which is the PEM data for the certificate. + + For example: + + ``` + -----BEGIN CERTIFICATE----- + MIIDWzCCAkOgAwIBAgIUY/wbeD1YUiEeBPLpxf8ldkkEE+swDQYJKoZIhvcNAQEL + BQAwMjELMAkGA1UEBhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9j + YWxob3N0MB4XDTIzMDMyMzEyNDAxMFoXDTIzMDYyMTEyNDAxMFowMjELMAkGA1UE + BhMCR0IxDzANBgNVBAcMBkxvbmRvbjESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjAN + BgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0bftLTaaXXpW1qIDHYTTmeIGvupy + G/dQpK5Ko9mW9IEcb+wfn2fX8SMHGA7O8TvpqUGEmyoBXIuIFmmeR+w5xQRcKkyi + NGhIhnUIfOqaevh4MCX/8Ius9NOjF0bz+aWtwOCmWKkNvknRMzClAeVRJm6g+U6m + IH30TE5H3ItiYxk63MNvuYeqIEK2rEKu69jWvTFkV1Wzd+5rH3ZC9qrt4uryUqAZ + X6XPx5AkQzbnBRQooDJzhqKgW+7YFWFtwi6WX8poGwx4RuruxYRLEBDfxRCE/1k6 + ALP3IktsVp7rFqwOt0LRNH1+MLly/MIOEA+NjnaIReG3/6Kt7oAqiDCBpQIDAQAB + o2kwZzAdBgNVHQ4EFgQU6WH9WjEM7cCwzCkNKYmu7vklicowHwYDVR0jBBgwFoAU + 6WH9WjEM7cCwzCkNKYmu7vklicowDwYDVR0TAQH/BAUwAwEB/zAUBgNVHREEDTAL + gglsb2NhbGhvc3QwDQYJKoZIhvcNAQELBQADggEBAIAELtWEMwzoXnaWRn74JngW + 3DF5IUtdFOiEKPWzdju+RleUsQHm5hsbPxpAz/MDVKIQQBGrJNMNpMtJ1VNlAsJ1 + 7gndSkSFf0zw7+DxgKYiwNj7tbBU8yTW+qVyUJh6XUxOHlaLjXzct4jw/NgjrjRZ + YuwXKCebRf+DUtQGt87rSib+GVpI//XBweyd8D0vFnGPRU9yyAvuqUdfu7enGFMr + qyBBqTqrTgX9o852lrMnWbc+g+of90Ym9HkVpifmc12jZSJlfS4cykvwnRqwPC9f + YnNABBMDJwJOM8g69OIRw+67O01ZulRzCvSaSbBEG6xC08XAD7BJn9CPIMypHdw= + -----END CERTIFICATE----- + ``` + +### Upload a public certificate + +**TODO:** Test where we reserve a certificate and the fetch CSR for the new certificate, sign it, and upload the result. + +## Content Protocol Discovery + +### List the Content Protocols available + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. List the Content Protocols for the Provisioning Session + + ```bash + m1-session protocols -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + + The available protocols will be listed. + + For example: + + ``` + Protocols for 40b75340-c8a3-41ed-9d6e-cbf27240da7a: + Downlink: + urn:3gpp:5gms:content-protocol:http-pull-ingest + No uplink capability + No geo-fencing capability + ``` + +## Content Hosting Provisioning + +### Add a Content Hosting Configuration without certificates + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create the hosting configuration: + + ```bash + m1-session set-stream -p ${provisioning_session_id} ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Check the provisioning session configuration: + + ```bash + m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + 2ef78712-c9a0-41ed-ac37-f9964ab0d12a: + Certificates: + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: http://localhost/m4d/provisioning-session-2ef78712-c9a0-41ed-ac37-f9964ab0d12a/ + Canonical Domain Name: localhost + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above can also be done using: +``` +m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` + +### Add a Content Hosting Configuration which uses an existing certificate + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a certificate: + + ```bash + m1-session new-certificate -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in the previous step. + +1. Generate a ContentHostingConfiguration using the certificate: + + ```bash + sed "s/@certificate-id@/${certificate_id}/g" ~/rt-5gms-application-function/examples/ContentHostingConfiguration_Big-Buck-Bunny_pull-ingest_https.json.tmpl > chc.json + ``` + + Where `${certificate_id}` is the certificate id of the certificate created in the previous step. + +1. Create the hosting configuration using the generated ContentHostingConfiguration: + + ```bash + m1-session set-stream -p ${provisioning_session_id} chc.json + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4. + +1. Check the provisioning session configuration: + + ```bash + m1-session list -v + ``` + + This will display the provisioning session created, showing no certificates and the details from the example + ContentHostingConfiguration. + + For example: + + ``` + ed5079d6-c9a4-41ed-b2ad-41232d457177: + Certificates: + fbd05ddc-c9a4-41ed-b2ad-41232d457177: + Serial = 186484472102456711697672477872825927418601662068 + Not before = 2023-03-23 18:03:15+00:00 + Not after = 2023-06-21 18:03:15+00:00 + Subject = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Issuer = C=GB,L=London,CN=localhost + key=8A:C2:9A:48:15:6A:15:BB:EE:B7:A0:9E:07:7C:CB:A4:CF:7C:51:F5 + Subject Alternative Names: + DNS:localhost + ContentHostingConfiguration: + Name: Big Buck Bunny + Entry Point Path: BigBuckBunny_4s_onDemand_2014_05_09.mpd + Ingest: + Type: urn:3gpp:5gms:content-protocol:http-pull-ingest + URL: https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/ + Distributions: + - URL: https://localhost/m4d/provisioning-session-ed5079d6-c9a4-41ed-b2ad-41232d457177/ + Canonical Domain Name: localhost + Certificate: fbd05ddc-c9a4-41ed-b2ad-41232d457177 + ``` + +**Note:** The `m1-session new-stream` command is a convience command that will create a provisioning session, generate the +ContentHostingConfiguration and set it in the newly created provisioning session. The above configuration with the `m1-session` tool can also be done using this single command instead: +``` +m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' --ssl-only 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' +``` + +## Consumption Reporting (v1.4.0 and later) + +### Add a Consumption Reporting Configuration + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Create a single Provisioning Session: + + ```bash + m1-session new-provisioning-session -e MyAppId -a MyASPId + ``` + + **Hint:** Set the shell variable `provisioning_session_id` to the returned provisioning session id for use in later commands. + +1. Create a Consumption Reporting Configuration for the Provisioning Session + ```bash + m1-session set-consumption-reporting -p ${provisioning_session_id} --interval 15 --sample-percentage 66.66 --location-reporting --access-reporting + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session that was created in step 4. + + This will set consumption reporting to every 15 seconds for 66.66% of clients and reports should include Location and Access reporting. + + All Consumption Reporting parameters are optional so doing the following: + ```bash + m1-session set-consumption-reporting -p ${provisioning_session_id} + ``` + ...will request all clients send a single Consumption Report at the end of the media without Location or Access reports (the defaults for consumption reporting). + +### Show current Consumption Reporting Configuration + +1. Display the current Consumption Reporting Configuration for a Provisioning Session + ```bash + m1-session show-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to view. + +### Remove the Consumption Reporting Configuration + +1. Remove Consumption Reporting from a Provisioning Session + ```bash + m1-session del-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to remove consumption reporting from. + +1. Display the current Consumption Reporting Configuration for the Provisioning Session to check it has gone + ```bash + m1-session show-consumption-reporting -p ${provisioning_session_id} + ``` + + Where `${provisioning_session_id}` is the provisioning session id of the session you wish to view. + + This will report no Consumption Reporting Configuration is present. diff --git a/pages/5g-media-streaming/testing/testing-m3-v110.md b/pages/5g-media-streaming/testing/testing-m3-v110.md new file mode 100644 index 00000000..9a26da25 --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m3-v110.md @@ -0,0 +1,216 @@ +--- +layout: default +title: Testing M3 AF v1.1.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 9 +--- + +# Testing: M3 Interface (5GMSd Application Function v1.1.x) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Configuration + +The Application Function is an M3 Client and most of the communication is only logged at the `debug` level. To properly see the M3 Interface interactions the configuration will need to set the minimum logging level to `debug` for the `msaf` domain. + +The example configurations all set the logging level for the `msaf` logging domain to `debug` and these configurations will be used throughout these tests. + +The `msaf.yaml` file in use by the Application Function is one of (in preference order): +- The file passed on the command line using the `-c` parameter. +- `${prefix}/etc/open5gs/msaf.yaml` + +These tests will use the `-c` command line parameter to override the location of the configuration file to use specific example +configurations for each test. + +Some tests also require an SSL public certificate and key to be generated. Appropriate instructions to generate self-signed certificastes are included in the test instructions where appropriate. + +For more information on configuring the Application Function (and generating self-signed certificates), see [Configuring the Application Function](Configuring-the-Application-Function). + +# Testing + +These tests require a [5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server) to be running. Please follow +the instructions to [build, install and run the 5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server#readme) as a system service or the [instructions to run the AS as a local user](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) for a temporary installation for testing. + +## Test Simple HTTP Configuration + +This will test the ability of the Application Function to configure an Application Server via the interface at M3 with a simple +HTTP (unencrypted) distribution. For this test a ContentHostingConfiguration is used which has no `certificateId` fields set in any `distributionConfiguration`. + +1. Stop the Application Function if it is already running. + +1. Start the Application Function with the `Test_http_canonical-msaf.yaml` example configuration, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd -c ~/rt-5gms-application-function/examples/Test_http_canonical-msaf.yaml + ``` + +1. The log output should indicate that the Application function: + 1. Requests a list of Server Certificates known by the Application Server (this is only done upon first communicating with an Application Server or when the Application Function needs to resynchronise the state from the Application Server) + + ``` + 02/10 10:39:26.792: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) + ``` + + There may be log output following this with a list of certificates known to the Application Server. + + 1. Requests the list of known provisioning session ids on the Application Server for ContentHostingConfigurations + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.837: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) + ``` + + There may be log output following this indicating a list of ContentHostingConfigurations known to the Application Server. + + 1. Pushes a new ContentHostingConfiguration to the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost] for Content Hosting Configuration: [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/application-server-context.c:235) + ``` + + 1. Receives a success (201) response back, removes the ContentHostingConfiguration from the upload queue and marks it as current configuration for the Application Server. + + ``` + 02/10 10:39:26.966: [msaf] DEBUG: [content-hosting-configurations] Method [POST] with Response [201] recieved for Content Hosting Configuration [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/msaf-sm.c:736) + 02/10 10:39:26.966: [msaf] DEBUG: Removing 30ef86aa-a92f-41ed-870f-4501bf315b24 from upload_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:745) + 02/10 10:39:26.966: [msaf] DEBUG: Adding 30ef86aa-a92f-41ed-870f-4501bf315b24 to current_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:747) + ``` + +## Test HTTPS configuration and certificate sending + +This will test the ability of the Application Function to configure an Application Server via the interface at M3 with a simple +HTTPS (encrypted) distribution, SSL/TLS private key and SSL/TLS public certificate. For this test a ContentHostingConfiguration is used which has `certificateId` fields set in the `distributionConfigurations`. + +1. Stop the Application Function if it is already running. + +1. Create the self-signed certificates. + + ```bash + cd ~/rt-5gms-application-function + subprojects/rt-common-shared/5gms/scripts/make_self_signed_certs.py --af-conf=examples/Test_https_canonical-msaf.yaml + ``` + + (see the information about [generating test certificates](Configuring-the-Application-Function#generating-test-certificates) + for more details) + +1. Start the Application Function with the `Test_https_canonical-msaf.yaml` example configuration, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd -c ~/rt-5gms-application-function/examples/Test_https_canonical-msaf.yaml + ``` + +1. The log output should indicate that the Application function: + 1. Requests a list of Server Certificates known by the Application Server (this is only done upon first communicating with an Application Server or when the Application Function needs to resynchronise the state from the Application Server) + + ``` + 02/10 10:39:26.792: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) + ``` + + There may be log output following this with a list of certificates known to the Application Server. + + 1. Requests the list of known provisioning session ids on the Application Server for ContentHostingConfigurations + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.837: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) + ``` + + There may be log output following this indicating a list of ContentHostingConfigurations known to the Application Server. + + 1. Pushes the private key and public certificate + + ``` + 02/10 10:39:26.838: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost]for Certificate: [30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1] (../src/5gmsaf/application-server-context.c:187 + ``` + + 1. Receives a success (201) response back, removes the Server Certificate from the upload queue and marks it as a current Server + Certificate for the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: [certificates] Method [POST] with Response [201] recieved for certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1] (../src/5gmsaf/msaf-sm.c:947) + 02/10 10:39:26.881: [msaf] DEBUG: Removing certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1] from upload_certificates (../src/5gmsaf/msaf-sm.c:958) + 02/10 10:39:26.881: [msaf] DEBUG: Adding certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1] to current_certificates (../src/5gmsaf/msaf-sm.c:962) + ``` + + 1. Pushes a new ContentHostingConfiguration to the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost] for Content Hosting Configuration: [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/application-server-context.c:235) + ``` + + 1. Receives a success (201) response back, removes the ContentHostingConfiguration from the upload queue and marks it as current configuration for the Application Server + + ``` + 02/10 10:39:26.966: [msaf] DEBUG: [content-hosting-configurations] Method [POST] with Response [201] recieved for Content Hosting Configuration [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/msaf-sm.c:736) + 02/10 10:39:26.966: [msaf] DEBUG: Removing 30ef86aa-a92f-41ed-870f-4501bf315b24 from upload_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:745) + 02/10 10:39:26.966: [msaf] DEBUG: Adding 30ef86aa-a92f-41ed-870f-4501bf315b24 to current_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:747) + ``` + + 1. Using the ProvisioningSessionId from the log output, check the configuration works via the Application Server using the generated certificate: + + ```bash + curl --cacert ~/rt-5gms-application-function/examples/certificate-1.pem -v https://localhost/m4d/provisioning-session-30ef86aa-a92f-41ed-870f-4501bf315b24/BigBuckBunny_4s_onDemand_2014_05_09.mpd + ``` + + ...or if you followed the "instructions to run the AS as a local user" then the port number used in the request URL will need to change to 8443, e.g + + ```bash + curl --cacert ~/rt-5gms-application-function/examples/certificate-1.pem -v https://localhost:8443/m4d/provisioning-session-30ef86aa-a92f-41ed-870f-4501bf315b24/BigBuckBunny_4s_onDemand_2014_05_09.mpd + ``` + + This should succeed and fetch the DASH MPD file for Big Buck Bunny. + +## Test state synchronisation + +If the Application Function is restarted without also restarting the Application Server, then the Application Server will retain +configurations (certificates and ContentHostingConfigurations) from older runs. This allows us to observe the state synchronisation +between the Application Function and Application Server so that the Application Function knows whether it needs to create or update entries. + +Perform this test by repeating the [Test HTTPS configuration and certificate sending](#test-https-configuration-and-certificate-sending) test a few times (the create self-signed certificate step can be skipped after the first time). After each restart you will observe the list of certificates and ContentHostingConfigurations known by the Application Server increase. For example: + +``` +02/10 11:51:20.871: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) +... +02/10 11:51:20.913: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) +02/10 11:51:20.913: [msaf] DEBUG: Adding certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1] to Current certificates (../src/5gmsaf/msaf-sm.c:1139) +02/10 11:51:20.913: [msaf] DEBUG: Adding certificate [b3e6c736-a938-41ed-b967-ff8e23a4f49f:testcert1] to Current certificates (../src/5gmsaf/msaf-sm.c:1139) +... +02/10 11:51:20.913: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) +... +02/10 11:51:20.916: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) +02/10 11:51:20.916: [msaf] DEBUG: Adding [30ef86aa-a92f-41ed-870f-4501bf315b24] to the current Content Hosting Configuration list (../src/5gmsaf/msaf-sm.c:913) +02/10 11:51:20.916: [msaf] DEBUG: Adding [b3e6c736-a938-41ed-b967-ff8e23a4f49f] to the current Content Hosting Configuration list (../src/5gmsaf/msaf-sm.c:913) +``` + +This shows the Application server already knows about: +- Certificates + - `30ef86aa-a92f-41ed-870f-4501bf315b24:testcert1` + - `b3e6c736-a938-41ed-b967-ff8e23a4f49f:testcert1` +- ContentHostingConfigurations + - `30ef86aa-a92f-41ed-870f-4501bf315b24` + - `b3e6c736-a938-41ed-b967-ff8e23a4f49f` + diff --git a/pages/5g-media-streaming/testing/testing-m3-v120.md b/pages/5g-media-streaming/testing/testing-m3-v120.md new file mode 100644 index 00000000..f3c62bbb --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m3-v120.md @@ -0,0 +1,231 @@ +--- +layout: default +title: Testing M3 AF v1.2.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 10 +--- + +# Testing: M3 Interface (5GMSd Application Function v1.2.0 and above) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Configuration + +The Application Function is an M3 Client and most of the communication is only logged at the `debug` level. To properly see the M3 Interface interactions the configuration will need to set the minimum logging level to `debug` for the `msaf` domain. + +To do this edit the installed `msaf.yaml` file and set the `logger` section to the following: + +```yaml +logger: + level: debug + domain: msaf +``` + +The `msaf.yaml` file in use by the Application Function is one of (in preference order): +- The file passed on the command line using the `-c` parameter. +- `${prefix}/etc/open5gs/msaf.yaml` + +The command for the tests will use the installed configuration file at `${prefix}/etc/open5gs/msaf.yaml`, if the instructions for [local user building and installation](Testing-as-a-Local-User) have been followed then this will be `~/rt-5gms-application-function/install/etc/open5gs/msaf.yaml`. You can optionally take a copy of this file and make the changes to a copy and then add the `-c` command line parameter and the path to your modified copy of the configuration file to the `open5gs-msafd` commands below. + +# Testing + +These tests require a [5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server) to be running. Please follow +the instructions to [build, install and run the 5GMSd Application Server](https://github.com/5G-MAG/rt-5gms-application-server#readme) as a system service or the [instructions to run the AS as a local user](https://github.com/5G-MAG/rt-5gms-application-server/wiki/Development-and-Testing) for a temporary installation for testing. + +## Test Simple HTTP Configuration + +This will test the ability of the Application Function to configure an Application Server via the interface at M3 with a simple +HTTP (unencrypted) distribution. For this test a ContentHostingConfiguration is used which has no `certificateId` fields set in any `distributionConfiguration`. + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple HTTP only stream hosting session: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. The log output should indicate that the Application function: + 1. Requests a list of Server Certificates known by the Application Server (this is only done upon first communicating with an Application Server or when the Application Function needs to resynchronise the state from the Application Server) + + ``` + 02/10 10:39:26.792: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) + ``` + + There may be log output following this with a list of certificates known to the Application Server. + + 1. Requests the list of known provisioning session ids on the Application Server for ContentHostingConfigurations + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.837: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) + ``` + + There may be log output following this indicating a list of ContentHostingConfigurations known to the Application Server. + + 1. Pushes a new ContentHostingConfiguration to the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost] for Content Hosting Configuration: [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/application-server-context.c:235) + ``` + + 1. Receives a success (201) response back, removes the ContentHostingConfiguration from the upload queue and marks it as current configuration for the Application Server. + + ``` + 02/10 10:39:26.966: [msaf] DEBUG: [content-hosting-configurations] Method [POST] with Response [201] recieved for Content Hosting Configuration [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/msaf-sm.c:736) + 02/10 10:39:26.966: [msaf] DEBUG: Removing 30ef86aa-a92f-41ed-870f-4501bf315b24 from upload_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:745) + 02/10 10:39:26.966: [msaf] DEBUG: Adding 30ef86aa-a92f-41ed-870f-4501bf315b24 to current_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:747) + ``` + +## Test HTTPS configuration and certificate sending + +This will test the ability of the Application Function to configure an Application Server via the interface at M3 with a simple +HTTPS (encrypted) distribution, SSL/TLS private key and SSL/TLS public certificate. For this test a ContentHostingConfiguration is used which has `certificateId` fields set in the `distributionConfigurations`. + +1. Stop the Application Function if it is already running. + +1. Remove previous configurations: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the Application Function: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple HTTPS only stream hosting session with self signed certificate: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e MyAppId -a MyASPId -n 'Big Buck Bunny' --ssl-only 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. The log output should indicate that the Application function: + 1. Requests a list of Server Certificates known by the Application Server (this is only done upon first communicating with an Application Server or when the Application Function needs to resynchronise the state from the Application Server) + + ``` + 02/10 10:39:26.792: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) + ``` + + There may be log output following this with a list of certificates known to the Application Server. + + 1. Requests the list of known provisioning session ids on the Application Server for ContentHostingConfigurations + + ``` + 02/10 10:39:26.834: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) + ``` + + 1. Receives the response + + ``` + 02/10 10:39:26.837: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) + ``` + + There may be log output following this indicating a list of ContentHostingConfigurations known to the Application Server. + + 1. Pushes the private key and public certificate + + ``` + 02/10 10:39:26.838: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost]for Certificate: [30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29] (../src/5gmsaf/application-server-context.c:187 + ``` + + 1. Receives a success (201) response back, removes the Server Certificate from the upload queue and marks it as a current Server + Certificate for the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: [certificates] Method [POST] with Response [201] recieved for certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29] (../src/5gmsaf/msaf-sm.c:947) + 02/10 10:39:26.881: [msaf] DEBUG: Removing certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29] from upload_certificates (../src/5gmsaf/msaf-sm.c:958) + 02/10 10:39:26.881: [msaf] DEBUG: Adding certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29] to current_certificates (../src/5gmsaf/msaf-sm.c:962) + ``` + + 1. Pushes a new ContentHostingConfiguration to the Application Server + + ``` + 02/10 10:39:26.881: [msaf] DEBUG: M3 client: Sending POST method to Application Server [localhost] for Content Hosting Configuration: [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/application-server-context.c:235) + ``` + + 1. Receives a success (201) response back, removes the ContentHostingConfiguration from the upload queue and marks it as current configuration for the Application Server + + ``` + 02/10 10:39:26.966: [msaf] DEBUG: [content-hosting-configurations] Method [POST] with Response [201] recieved for Content Hosting Configuration [30ef86aa-a92f-41ed-870f-4501bf315b24] (../src/5gmsaf/msaf-sm.c:736) + 02/10 10:39:26.966: [msaf] DEBUG: Removing 30ef86aa-a92f-41ed-870f-4501bf315b24 from upload_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:745) + 02/10 10:39:26.966: [msaf] DEBUG: Adding 30ef86aa-a92f-41ed-870f-4501bf315b24 to current_content_hosting_configurations (../src/5gmsaf/msaf-sm.c:747) + ``` + + 1. Using the ProvisioningSessionId from the log output, check the configuration works via the Application Server using the generated certificate: + + ```bash + curl -k -v https://localhost/m4d/provisioning-session-30ef86aa-a92f-41ed-870f-4501bf315b24/BigBuckBunny_4s_onDemand_2014_05_09.mpd + ``` + + ...or if you followed the "instructions to run the AS as a local user" then the port number used in the request URL will need to change to 8443, e.g + + ```bash + curl -k -v https://localhost:8443/m4d/provisioning-session-30ef86aa-a92f-41ed-870f-4501bf315b24/BigBuckBunny_4s_onDemand_2014_05_09.mpd + ``` + + This should succeed and fetch the DASH MPD file for Big Buck Bunny. + +## Test state synchronisation + +If the Application Function is restarted without also restarting the Application Server, then the Application Server will retain +configurations (certificates and ContentHostingConfigurations) from older runs. This allows us to observe the state synchronisation +between the Application Function and Application Server so that the Application Function knows whether it needs to create or update entries. + +Perform this test by performing the [Test HTTPS configuration and certificate sending](#test-https-configuration-and-certificate-sending) test and repeating step 4 (`m1-session` command) a few times, then perform the test once more from the beginning. You will observe the list of certificates and ContentHostingConfigurations known by the Application Server include the identifiers generated in the first run by the several `m1-session` commands. For example: + +``` +02/10 11:51:20.871: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known certificates (../src/5gmsaf/application-server-context.c:151) +... +02/10 11:51:20.913: [msaf] DEBUG: [certificates] Method [GET] with Response [200] received (../src/5gmsaf/msaf-sm.c:1111) +02/10 11:51:20.913: [msaf] DEBUG: Adding certificate [30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29] to Current certificates (../src/5gmsaf/msaf-sm.c:1139) +02/10 11:51:20.913: [msaf] DEBUG: Adding certificate [b3e6c736-a938-41ed-b967-ff8e23a4f49f:04844ed2-b8f5-4e22-b948-2b939fc2e21c] to Current certificates (../src/5gmsaf/msaf-sm.c:1139) +... +02/10 11:51:20.913: [msaf] DEBUG: M3 client: Sending GET method to Application Server [localhost] to request the list of known content-hosting-configurations (../src/5gmsaf/application-server-context.c:154) +... +02/10 11:51:20.916: [msaf] DEBUG: [content-hosting-configurations] Method [GET] with Response [200] for Content Hosting Configuration operation [(null)] (../src/5gmsaf/msaf-sm.c:888) +02/10 11:51:20.916: [msaf] DEBUG: Adding [30ef86aa-a92f-41ed-870f-4501bf315b24] to the current Content Hosting Configuration list (../src/5gmsaf/msaf-sm.c:913) +02/10 11:51:20.916: [msaf] DEBUG: Adding [b3e6c736-a938-41ed-b967-ff8e23a4f49f] to the current Content Hosting Configuration list (../src/5gmsaf/msaf-sm.c:913) +``` + +This example shows the Application server already knows about: +- Certificates + - `30ef86aa-a92f-41ed-870f-4501bf315b24:ea94917c-3726-45c5-9706-b6bb0be77e29` + - `b3e6c736-a938-41ed-b967-ff8e23a4f49f:04844ed2-b8f5-4e22-b948-2b939fc2e21c` +- ContentHostingConfigurations + - `30ef86aa-a92f-41ed-870f-4501bf315b24` + - `b3e6c736-a938-41ed-b967-ff8e23a4f49f` + diff --git a/pages/5g-media-streaming/testing/testing-m5-v100.md b/pages/5g-media-streaming/testing/testing-m5-v100.md new file mode 100644 index 00000000..77a5f74a --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m5-v100.md @@ -0,0 +1,306 @@ +--- +layout: default +title: Testing M5 AF v1.0.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 11 +--- + +# Testing: M5 Interface (5GMSd Application Function v1.0.0 to v1.1.x) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Configuration + +These tests use test configurations from the `examples` directory. Some of these example configuration will need self-signed public certificates generating, and appropriate instructions are included to run the generation script with the correct configuration where appropriate. + +The `msaf.yaml` file in use by the Application Function is one of (in preference order): +- The file passed on the command line using the `-c` parameter. +- `${prefix}/etc/open5gs/msaf.yaml` + +These tests use the `-c` command line parameter to override the default configuration location. + +See [Configuring the Application Function](Configuring-the-Application-Function) for more details on Application Function +configuration. + +# Testing + +This section will describe common tests and the expected outcomes for the M5 interface. + +**Note: At this time the only implemented part of the M5 interface is the ServiceAccessInformation API** + +## M5 API prefix + +The current implementation of the interface at M5 uses the URL prefix of `http://${msaf.sbi.addr}:${msaf.sbi.port}/3gpp-m5/v2/`, +no other versions (i.e. "v2" only) are implemented and attempts to use another version will result a 400 Bad Request error response. + +### Unsupported M5 API version + +Test URL: `http://${msaf.sbi.addr}:${msaf.sbi.port}/3gpp-m5/v1/service-access-information` +Example command: `curl -v 'http://127.0.0.1:7778/3gpp-m5/v1/service-access-information'` + +Expected result: +``` +> GET /3gpp-m5/v1/service-access-information/id HTTP/1.1 +> Host: 127.0.0.1:7778 +> User-Agent: curl/7.85.0 +> Accept: */* +> +< HTTP/1.1 400 Bad Request +< Date: Tue, 07 Feb 2023 11:46:59 GMT +< Connection: close +< Content-Type: application/problem+json +< Content-Length: 124 +< +{ + "type": "/3gpp-m5/v1", + "title": "Not supported version", + "status": 400, + "instance": "/service-access-information" +} +``` +**Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + +AF log output: +``` +02/07 11:46:59.263: [msaf] ERROR: Not supported version [v1] (../src/5gmsaf/msaf-sm.c:494) +``` + +The HTTP response is a 400 status code with a ProblemDetail JSON object in the body. The problem detail shows that the error +happened because the request contained an unsupported version. The application itself produces an `ERROR` log message indicating +that a client requested an unsupported version. + +## ServiceAccessInformation + +These tests describe the available actions and possible responses for the M5 ServiceAccessInformation APIs. + +Interface URL: `http://${msaf.sbi.addr}:${msaf.sbi.port}/3gpp-m5/v2/service-access-information/${provisioningSessionId}` + +Where `${provisioningSessionId}` is the provisioning session identifier for the provisioning session. In a full 5GMSd Application +Function this would come from the `Location` in the response on the interface at M1 to a createProvisioningSession API action. +However, in the current version of the 5GMSd Application Function there is only one provisioning session created at start up. The +currently valid provisioning session id can be found in the log output from the `open5gs-msafd` command in the line containing +"INFO: Provisioning session = ". + +### Testing Success + +#### Testing the unencrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration does not contain any `distributionConfigurations.certificateId` or +`distributionConfigurations.domainNameAlias` properties then the `mediaPlayerEntry` in the ServiceAccessInformation will use the +"http" protocol and the canonical hostname of the 5GMSd Application Server as the authority part. + +1. Stop the AF if it is running. + +1. Start the AF with the `Test_http_canonical-msaf.yaml` example configuration, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd -c ~/rt-5gms-application-function/examples/Test_http_canonical-msaf.yaml + ``` + +1. Using the provisioning session id from the AF log output perform a GET request on the interface URL. + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.1:7778/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.1:7778 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "http://localhost/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL for the canonical name set in the + `msaf.yaml` file in the `msaf.applicationServers.canonicalHostname` property, and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the ContentHostingConfiguration). + +#### Testing the encrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration contains `distributionConfigurations.certificateId` properties then an "https://" will be used +for the `mediaPlayerEntry` in the ServiceAccessInformation. + +1. Stop the AF if it is running. + +1. Create the self signed certificate: + + ```bash + cd ~/rt-5gms-application-function + subprojects/rt-common-shared/5gms/scripts/make_self_signed_certs.py --af-conf=examples/Test_https_canonical-msaf.yaml + ``` + + (see the information about [generating test certificates](Configuring-the-Application-Function#generating-test-certificates) + for more details) + +1. Start the AF with the `Test_https_canonical-msaf.yaml` configuration, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd -c ~/rt-5gms-application-function/examples/Test_https_canonical-msaf.yaml + ``` + +1. Using the provisioning session id from the AF log output perform a GET request on the interface URL. + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.1:7778/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.1:7778 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "https://localhost/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "https://" URL (to show the AF is giving + preference to the HTTPS access point) for the canonical name `localhost` (set in the `Test_https_canonical-msaf.yaml` file in the + `msaf.applicationServers.canonicalHostname` property), and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the ContentHostingConfiguration). + +#### Testing the `mediaPlayerEntry` when providing a `domainNameAlias` + +If the ContentHostingConfiguration given in the `msaf.yaml` configuration file includes a +`distributionConfigurations.domainNameAlias` then this hostname will be used as the authority for the `mediaPlayerEntry` in the +ServiceAccessInformation in preference to the canonical hostname of the AS. + +To test this: +1. Stop the AF process. + +1. Start the AF with the `Test_http_domain_alias-msaf.yaml` configuration, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd -c ~/rt-5gms-application-function/examples/Test_http_domain_alias-msaf.yaml + ``` + +1. Using the provisioning session id from the AF log output perform a GET request on the interface URL. + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.1:7778/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.1:7778 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "https://media.example.com/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL followed by the + `distributionConfigurations.domainNameAlias` property from the example + `ContentHostingConfiguration_Big-Buck-Bunny_domain-name_http.json` file, and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` from the `Test_http_domain_alias-msaf.yaml` configuration file and ending in + "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the `entryPointPath` in the ContentHostingConfiguration). + + +### Testing No Such Provisioning Session + +If the `${provisioningSessionId}` used in the request URL does not exist as an active provisioning session in the AF then the +HTTP response will be a 404 Not Found status code. + +To test this +1. Start the AF if it is not already running, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Using a bogus provisioning session id, perform a GET request on the interface URL. + + For example, if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c, then for this test we use a provisioning session id string that does not match that id. + + Example command using `does-not-exist` as a provisioning session id: + + ```bash + curl -v 'http://127.0.0.1:7778/3gpp-m5/v2/service-access-information/does-not-exist' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/does-not-exist HTTP/1.1 + > Host: 127.0.0.1:7778 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 404 Not Found + < Date: Tue, 07 Feb 2023 14:47:26 GMT + < Connection: close + < Content-Type: application/problem+json + < Content-Length: 208 + < + { + "type": "/3gpp-m5/v2", + "title": "Provisioning Session not found", + "status": 404, + "detail": "Provisioning Session [does-not-exist] not found.", + "instance": "/service-access-information/does-not-exist" + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 404 status code with the body containing a ProblemDetail JSON object. diff --git a/pages/5g-media-streaming/testing/testing-m5-v120.md b/pages/5g-media-streaming/testing/testing-m5-v120.md new file mode 100644 index 00000000..c34257ce --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m5-v120.md @@ -0,0 +1,334 @@ +--- +layout: default +title: Testing M5 AF v1.2.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 12 +--- + +# Testing: M5 Interface (5GMSd Application Function v1.2.x) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Configuration + +These tests use test configurations from the `examples` directory. Some of these example configuration will need self-signed public certificates generating, and appropriate instructions are included to run the generation script with the correct configuration where appropriate. + +The `msaf.yaml` file in use by the Application Function is one of (in preference order): +- The file passed on the command line using the `-c` parameter. +- `${prefix}/etc/open5gs/msaf.yaml` + +These tests use the `-c` command line parameter to override the default configuration location. + +See [Configuring the Application Function](Configuring-the-Application-Function) for more details on Application Function +configuration. + +# Testing + +This section will describe common tests and the expected outcomes for the M5 interface. + +**Note: At this time the only implemented part of the M5 interface is the ServiceAccessInformation API** + +## M5 API prefix + +The current implementation of the interface at M5 uses the URL prefix of `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v2/`, +no other versions (i.e. "v2" only) are implemented and attempts to use another version will result a 400 Bad Request error response. + +### Unsupported M5 API version + +Test URL: `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v1/service-access-information` +Example command: `curl -v 'http://127.0.0.24:7777/3gpp-m5/v1/service-access-information'` + +Expected result: +``` +> GET /3gpp-m5/v1/service-access-information HTTP/1.1 +> Host: 127.0.0.24:7777 +> User-Agent: curl/7.85.0 +> Accept: */* +> +< HTTP/1.1 400 Bad Request +< Date: Tue, 07 Feb 2023 11:46:59 GMT +< Connection: close +< Content-Type: application/problem+json +< Content-Length: 124 +< +{ + "type": "/3gpp-m5/v1", + "title": "Not supported version", + "status": 400, + "instance": "/service-access-information" +} +``` +**Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + +AF log output: +``` +02/07 11:46:59.263: [msaf] ERROR: Not supported version [v1] (../src/5gmsaf/msaf-sm.c:494) +``` + +The HTTP response is a 400 status code with a ProblemDetail JSON object in the body. The problem detail shows that the error +happened because the request contained an unsupported version. The application itself produces an `ERROR` log message indicating +that a client requested an unsupported version. + +## ServiceAccessInformation + +These tests describe the available actions and possible responses for the M5 ServiceAccessInformation APIs. + +Interface URL: `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v2/service-access-information/${provisioningSessionId}` + +Where `${provisioningSessionId}` is the provisioning session identifier for the provisioning session. This URL comes from the `Location` in the response on the interface at M1 to a createProvisioningSession API action, and is displayed by the `m1-session` tool when a `new-provisioning-session` or `new-stream` command is successful. + +### Testing Success + +#### Testing the unencrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration does not contain any `distributionConfigurations.certificateId` or +`distributionConfigurations.domainNameAlias` properties then the `mediaPlayerEntry` in the ServiceAccessInformation will use the +"http" protocol and the canonical hostname of the 5GMSd Application Server as the authority part. + +1. Stop the AF if it is running. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL. + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "http://localhost/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL for the canonical name set in the + `msaf.yaml` file in the `msaf.applicationServers.canonicalHostname` property, and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the `m1-session` command). + +#### Testing the encrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration contains `distributionConfigurations.certificateId` properties then an "https://" will be used +for the `mediaPlayerEntry` in the ServiceAccessInformation. + +1. Stop the AF if it is running. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream with self-signed HTTPS distribution: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple HTTPS Stream' --with-ssl 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "https://localhost/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "https://" URL (to show the AF is giving + preference to the HTTPS access point) for the canonical name `localhost` (set in the `msaf.yaml` file in the + `msaf.applicationServers.canonicalHostname` property), and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the `m1-session` command). + +#### Testing the `mediaPlayerEntry` when providing a `domainNameAlias` + +If the ContentHostingConfiguration given in the `msaf.yaml` configuration file includes a +`distributionConfigurations.domainNameAlias` then this hostname will be used as the authority for the `mediaPlayerEntry` in the +ServiceAccessInformation in preference to the canonical hostname of the AS. + +To test this: +1. Stop the AF process. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream with self-signed HTTPS distribution: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple HTTPS Stream' -d 'media.example.com' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Tue, 07 Feb 2023 12:11:56 GMT + < Connection: close + < Content-Type: application/json + < Content-Length: 278 + < + { + "provisioningSessionId": "0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "mediaPlayerEntry": "https://media.example.com/m4d/provisioning-session-0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c/BigBuckBunny_4s_onDemand_2014_05_09.mpd" + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL followed by the + `media.example.com` FQDN given with the `-d` command line argument to the `m1-session` command, and a path starting with the + value of the `msaf.applicationServers.urlPathPrefixFormat` from the `msaf.yaml` configuration file and ending in + "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the `entryPointPath` given on the `m1-session` command line). + + +### Testing No Such Provisioning Session + +If the `${provisioningSessionId}` used in the request URL does not exist as an active provisioning session in the AF then the +HTTP response will be a 404 Not Found status code. + +To test this +1. Start the AF if it is not already running, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using a bogus provisioning session id, i.e. anything except the provisioning session id returned by the `m1-session` command, + perform a GET request on the interface URL. + + For example, if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c, then for this test we use a provisioning session id string that does not match that id. + + Example command using `does-not-exist` as a provisioning session id: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/does-not-exist' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/does-not-exist HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 404 Not Found + < Date: Tue, 07 Feb 2023 14:47:26 GMT + < Connection: close + < Content-Type: application/problem+json + < Content-Length: 208 + < + { + "type": "/3gpp-m5/v2", + "title": "Provisioning Session not found", + "status": 404, + "detail": "Provisioning Session [does-not-exist] not found.", + "instance": "/service-access-information/does-not-exist" + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 404 status code with the body containing a ProblemDetail JSON object. diff --git a/pages/5g-media-streaming/testing/testing-m5-v130.md b/pages/5g-media-streaming/testing/testing-m5-v130.md new file mode 100644 index 00000000..8ae6ab70 --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-m5-v130.md @@ -0,0 +1,368 @@ +--- +layout: default +title: Testing M5 AF v1.3.x +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 13 +--- + +# Testing: M5 Interface (5GMSd Application Function v1.3.0 and above) + +To prepare, follow the instructions for [local user building and installation](Testing-as-a-Local-User). + +# Configuration + +These tests use test configurations from the `examples` directory. Some of these example configuration will need self-signed public certificates generating, and appropriate instructions are included to run the generation script with the correct configuration where appropriate. + +The `msaf.yaml` file in use by the Application Function is one of (in preference order): +- The file passed on the command line using the `-c` parameter. +- `${prefix}/etc/open5gs/msaf.yaml` + +These tests use the `-c` command line parameter to override the default configuration location. + +See [Configuring the Application Function](Configuring-the-Application-Function) for more details on Application Function +configuration. + +# Testing + +This section will describe common tests and the expected outcomes for the M5 interface. + +**Note: At this time the only implemented part of the M5 interface is the ServiceAccessInformation API** + +## M5 API prefix + +The current implementation of the interface at M5 uses the URL prefix of `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v2/`, +no other versions (i.e. "v2" only) are implemented and attempts to use another version will result a 400 Bad Request error response. + +### Unsupported M5 API version + +Test URL: `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v1/service-access-information` +Example command: `curl -v 'http://127.0.0.24:7777/3gpp-m5/v1/service-access-information'` + +Expected result: +``` +> GET /3gpp-m5/v1/service-access-information HTTP/1.1 +> Host: 127.0.0.24:7777 +> User-Agent: curl/7.85.0 +> Accept: */* +> +< HTTP/1.1 400 Bad Request +< Date: Tue, 07 Feb 2023 11:46:59 GMT +< Connection: close +< Content-Type: application/problem+json +< Content-Length: 124 +< +{ + "type": "/3gpp-m5/v1", + "title": "Not supported version", + "status": 400, + "instance": "/service-access-information" +} +``` +**Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + +AF log output: +``` +02/07 11:46:59.263: [msaf] ERROR: Not supported version [v1] (../src/5gmsaf/msaf-sm.c:494) +``` + +The HTTP response is a 400 status code with a ProblemDetail JSON object in the body. The problem detail shows that the error +happened because the request contained an unsupported version. The application itself produces an `ERROR` log message indicating +that a client requested an unsupported version. + +## ServiceAccessInformation + +These tests describe the available actions and possible responses for the M5 ServiceAccessInformation APIs. + +Interface URL: `http://${msaf.m5.addr}:${msaf.m5.port}/3gpp-m5/v2/service-access-information/${provisioningSessionId}` + +Where `${provisioningSessionId}` is the provisioning session identifier for the provisioning session. This URL comes from the `Location` in the response on the interface at M1 to a createProvisioningSession API action, and is displayed by the `m1-session` tool when a `new-provisioning-session` or `new-stream` command is successful. + +### Testing Success + +#### Testing the unencrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration does not contain any `distributionConfigurations.certificateId` or +`distributionConfigurations.domainNameAlias` properties then the `mediaPlayerEntry` in the ServiceAccessInformation will use the +"http" protocol and the canonical hostname of the 5GMSd Application Server as the authority part. + +1. Stop the AF if it is running. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL. + + Example command if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/f863831c-daa8-41ed-862b-c1f4c44bccf3 HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Fri, 14 Apr 2023 09:44:47 GMT + < Connection: close + < Content-Type: application/json + < ETag: 38548172d8eca143db6b4b11af8df6dea66d62acb45f751c9348f257c9682165 + < Last-Modified: Fri, 14 Apr 2023 09:44:37 GMT + < Cache-Control: max-age=60 + < Server: 5GMSdAF-localhost/17 (info.title=M5_ServiceAccessInformation; info.version=2.2.0) rt-5gms-application-function/1.3.0 + < Content-Length: 339 + { + "provisioningSessionId": "f863831c-daa8-41ed-862b-c1f4c44bccf3", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "entryPoints": [{ + "locator": "http://localhost/m4d/provisioning-session-f863831c-daa8-41ed-862b-c1f4c44bccf3/BigBuckBunny_4s_onDemand_2014_05_09.mpd", + "contentType": "application/dash+xml" + }] + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL for the canonical name set in the + `msaf.yaml` file in the `msaf.applicationServers.canonicalHostname` property, and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the `m1-session` command). + +#### Testing the encrypted media entry point on the canonical hostname + +If the ContentHostingConfiguration contains `distributionConfigurations.certificateId` properties then an "https://" will be used +for the `mediaPlayerEntry` in the ServiceAccessInformation. + +1. Stop the AF if it is running. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream with self-signed HTTPS distribution: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple HTTPS Stream' --with-ssl 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL + + Example command if the provisioning session id is 30c20cea-daab-41ed-87fe-93ba2b9b790a: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/30c20cea-daab-41ed-87fe-93ba2b9b790a' + ``` + + Expected result should look like: + + ``` + > GET /3gpp-m5/v2/service-access-information/30c20cea-daab-41ed-87fe-93ba2b9b790a HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Fri, 14 Apr 2023 10:00:40 GMT + < Connection: close + < ETag: 8c12228d39cd5e015fdab5e7972084a6bbd12747b4c482e0cdc1ce82bbac597e + < Last-Modified: Fri, 14 Apr 2023 10:00:31 GMT + < Cache-Control: max-age=60 + < Server: 5GMSdAF-localhost/17 (info.title=M5_ServiceAccessInformation; info.version=2.2.0) rt-5gms-application-function/1.3.0 + < Content-Type: application/json + < Content-Length: 340 + < + { + "provisioningSessionId": "30c20cea-daab-41ed-87fe-93ba2b9b790a", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "entryPoints": [{ + "locator": "https://localhost/m4d/provisioning-session-30c20cea-daab-41ed-87fe-93ba2b9b790a/BigBuckBunny_4s_onDemand_2014_05_09.mpd", + "contentType": "application/dash+xml" + }] + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "https://" URL (to show the AF is giving + preference to the HTTPS access point) for the canonical name `localhost` (set in the `msaf.yaml` file in the + `msaf.applicationServers.canonicalHostname` property), and a path starting with the value of the + `msaf.applicationServers.urlPathPrefixFormat` and ending in "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the + `entryPointPath` in the `m1-session` command). + +#### Testing the `mediaPlayerEntry` when providing a `domainNameAlias` + +If the ContentHostingConfiguration given in the `msaf.yaml` configuration file includes a +`distributionConfigurations.domainNameAlias` then this hostname will be used as the authority for the `mediaPlayerEntry` in the +ServiceAccessInformation in preference to the canonical hostname of the AS. + +To test this: +1. Stop the AF process. + +1. Clean up old persistent data: + + ```bash + rm -rf ~/rt-5gms-application-function/install/var/cache/rt-5gms/af/certificates + ``` + +1. Start the AF: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream with self-signed HTTPS distribution: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple HTTPS Stream' -d 'media.example.com' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using the provisioning session id, returned from the `m1-session` command, perform a GET request on the interface URL + + Example command if the provisioning session id is efbff530-daab-41ed-87fe-93ba2b9b790a: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/efbff530-daab-41ed-87fe-93ba2b9b790a' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/efbff530-daab-41ed-87fe-93ba2b9b790a HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 200 OK + < Date: Fri, 14 Apr 2023 10:06:01 GMT + < Connection: close + < ETag: f5dd70a781efeefed1c034bbe640119019e1a46a55dcf50cfcccae8a323139ad + < Last-Modified: Fri, 14 Apr 2023 10:05:51 GMT + < Cache-Control: max-age=60 + < Server: 5GMSdAF-localhost/17 (info.title=M5_ServiceAccessInformation; info.version=2.2.0) rt-5gms-application-function/1.3.0 + < Content-Type: application/json + < Content-Length: 347 + < + { + "provisioningSessionId": "efbff530-daab-41ed-87fe-93ba2b9b790a", + "provisioningSessionType": "DOWNLINK", + "streamingAccess": { + "entryPoints": [{ + "locator": "http://media.example.com/m4d/provisioning-session-efbff530-daab-41ed-87fe-93ba2b9b790a/BigBuckBunny_4s_onDemand_2014_05_09.mpd", + "contentType": "application/dash+xml" + }] + } + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 200 status code with the body containing a ServiceAccessInformation JSON object. The + `provisioningSessionId` in the ServiceAccessInformation object should match the id presented in the request URL. The + `provisioningSessionType` will be "DOWNLINK". The `mediaPlayerEntry` will be a "http://" URL followed by the + `media.example.com` FQDN given with the `-d` command line argument to the `m1-session` command, and a path starting with the + value of the `msaf.applicationServers.urlPathPrefixFormat` from the `msaf.yaml` configuration file and ending in + "`/BigBuckBunny_4s_onDemand_2014_05_09.mpd`" (which comes from the `entryPointPath` given on the `m1-session` command line). + + +### Testing No Such Provisioning Session + +If the `${provisioningSessionId}` used in the request URL does not exist as an active provisioning session in the AF then the +HTTP response will be a 404 Not Found status code. + +To test this +1. Start the AF if it is not already running, e.g.: + + ```bash + ~/rt-5gms-application-function/install/bin/open5gs-msafd + ``` + +1. Configure a simple stream: + + ```bash + ~/rt-5gms-application-function/install/bin/m1-session new-stream -e AppId -n 'Simple Stream' 'https://ftp.itec.aau.at/datasets/DASHDataset2014/BigBuckBunny/4sec/' 'BigBuckBunny_4s_onDemand_2014_05_09.mpd' + ``` + +1. Using a bogus provisioning session id, i.e. anything except the provisioning session id returned by the `m1-session` command, + perform a GET request on the interface URL. + + For example, if the provisioning session id is 0c5cc9e6-a6dd-41ed-ae90-e781c44d0f0c, then for this test we use a provisioning session id string that does not match that id. + + Example command using `does-not-exist` as a provisioning session id: + + ```bash + curl -v 'http://127.0.0.24:7777/3gpp-m5/v2/service-access-information/does-not-exist' + ``` + + Expected result: + + ``` + > GET /3gpp-m5/v2/service-access-information/does-not-exist HTTP/1.1 + > Host: 127.0.0.24:7777 + > User-Agent: curl/7.85.0 + > Accept: */* + > + < HTTP/1.1 404 Not Found + < Date: Tue, 07 Feb 2023 14:47:26 GMT + < Connection: close + < Server: 5GMSdAF-localhost/17 (info.title=M5_ServiceAccessInformation; info.version=2.2.0) rt-5gms-application-function/1.3.0 + < Content-Type: application/problem+json + < Content-Length: 208 + < + { + "type": "/3gpp-m5/v2", + "title": "Provisioning Session not found", + "status": 404, + "detail": "Provisioning Session [does-not-exist] not found.", + "instance": "/service-access-information/does-not-exist" + } + ``` + **Note:** There may also be additional HTTP library information lines output by curl starting with a `*` character interspersed with the output. + + The HTTP response is a 404 status code with the body containing a ProblemDetail JSON object. + +## Consumption Reporting + +**TODO!** + +## Network Assistance + +**TODO!** + +## Dynamic Policies + +**TODO!** + diff --git a/pages/5g-media-streaming/testing/testing-postman.md b/pages/5g-media-streaming/testing/testing-postman.md new file mode 100644 index 00000000..016b9411 --- /dev/null +++ b/pages/5g-media-streaming/testing/testing-postman.md @@ -0,0 +1,74 @@ +--- +layout: default +title: Testing with Postman +parent: Testing +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 5 +--- + +# Testing with Postman +[Postman](https://www.postman.com/) is a popular API development and testing tool that allows users to create, send, and manage HTTP requests. It provides a user-friendly interface for building and testing API endpoints, making it easier for developers to collaborate and streamline the API development process. Postman comes in very handy when testing and working with the `M1` and `M5` interfaces of the Application Function. + +# Importing the 5G-MAG Postman Collection +Postman provides an easy way to export and import a collection of REST calls. To facilitate getting started, you can download our pre-defined Postman collections and environment here: + +* [5G-MAG M1.postman_collection.json](https://github.com/5G-MAG/rt-5gms-application-function/files/14064359/5G-MAG.M1.postman_collection.json) +* [5G-MAG M5.postman_collection.json](https://github.com/5G-MAG/rt-5gms-application-function/files/14062693/5G-MAG.M5.postman_collection.json) +* [5G-MAG.postman_environment.json](https://github.com/5G-MAG/rt-5gms-application-function/files/14062716/5G-MAG.postman_environment.json) + + +After the download, open Postman and select `File->Import`. After a successful import, you should see two collections like this: + +Bildschirmfoto 2024-01-26 um 09 07 00 + +# Postman Configuration +A very useful feature of Postman is the possibility to define variables. These variables can afterward be used in any of our routes or payloads. The first variables we need to define are the `m1_url` and `m5_url` variables. For that reason, select `Environments` on the left side and then select the `5G-MAG` environment. Now you should see a list of variables similar to this: + +Bildschirmfoto 2024-01-26 um 09 15 05 + +Add the URL to the `M1` and the `M5` endpoint of your Application Function here. In the example above, we are running the Application Function in a local network. Note that both URLs also need to contain the port. The configuration options for the Application Function are documented [here](https://github.com/5G-MAG/rt-5gms-application-function/wiki/Configuring-the-Application-Function). + +# Using M1 +Now that we have defined the `M1` endpoint, we can start using it: + +## Creating a Provisioning Session +Navigate to the `Provisioning Session` folder in the Postman Collection and select `Create Provisioning Session`. Check the URL on the top that we are sending the request to: `{{m1_url}}/3gpp-m1/v2/provisioning-sessions`. Here you can see that we are using the `m1_url` variable that we defined earlier. If the endpoint changes at some point we only need to change our variable instead of all the M1 calls in our Postman collection. + +Click on `Send` on the top right. You should see a successful response (status code `201`) and the payload of the response on the bottom: + +Bildschirmfoto 2024-01-26 um 09 28 04 + + +The response body contains the `provisioningSessionId` of our created provisioning session. The `provisioningSessionId` is an important identifier and used in many of the `M1` and `M5` endpoints. Consequently, it makes sense to assign the `provisioningSessionId` to a variable as well. Our collection contains a small script that automatically assigns the `provisioningSessionId` value of the response body to the `provisioning_session_id` variable: + +````js +var responseBody = pm.response.json(); +var provisioningSessionId = responseBody.provisioningSessionId; +pm.environment.set("provisioning_session_id", provisioningSessionId); +```` + +## Retrieving a Provisioning Session +Now that we have created a provisioning session and assigned its `provisioningSessionId` to our variable, we can directly call the `GET Provisioning Session` endpoint. As expected, our route contains the `m1_url` and the `provisioning_session_id` variable: `{{m1_url}}/3gpp-m1/v2/provisioning-sessions/{{provisioning_session_id}}`. + +Sending this request should result in a response similar to this: +Bildschirmfoto 2024-01-26 um 09 36 19 + +## Deleting a Provisioning Session +Deleting a provisioning session is straight forward as well. As we already defined the required variables, you can simply execute the call and should receive a `202 Accepted` response. + +## Consumption Reporting +To manage consumption reporting configurations, proceed similarly to managing provisioning sessions. Note that the `create` and `update` functions contain a `JSON` structure in the payload to define the required parameters. + +## Policy Templates +To manage policy templates, proceed similarly to managing provisioning sessions. Note that the `create` and `update` functions contain a `JSON` structure in the payload to define the required parameters. Moreover, `open5gsIntegration` must be enabled in the configuration of the Application Function. For more details, refer to the [Configuration Guide](https://github.com/5G-MAG/rt-5gms-application-function/wiki/Configuring-the-Application-Function). + +After successfully creating a policy template, the new `policyTemplateId` contained in the `Location` header is automatically assigned to the `policy_template_id` variable: + +````js +var policyTemplateId = pm.response.headers.get("Location").split("/").pop() +pm.environment.set("policy_template_id", policyTemplateId); +```` + +# Using M5 +The `M5` routes to query the Service Access Information, send a Consumption Report, create a Dynamic Policy resource and provision a new Network Assistance Session can be found in the `5G-MAG M5` folder. There is no additional configuration required, the routes for `M5` use the variables that we defined earlier as part of the configuration and the execution of `M1` endpoints. diff --git a/pages/5g-media-streaming/tutorials/configuration-5GMSAF.md b/pages/5g-media-streaming/tutorials/configuration-5GMSAF.md new file mode 100644 index 00000000..e8703261 --- /dev/null +++ b/pages/5g-media-streaming/tutorials/configuration-5GMSAF.md @@ -0,0 +1,437 @@ +--- +layout: default +title: Configuration 5GMS AF +parent: Tutorials +grand_parent: 5G Downlink Media Streaming +has_children: false +nav_order: 1 +--- + +# Configuration of the 5GMSd Application Function + +The configuration file for the 5GMSd Application function contains several settings + +## File Locations + +The configuration file for the 5GMSd Application Function can be found in `${prefix}/etc/open5gs/msaf.yaml`, where `${prefix}` is +the prefix used in the `meson` command (or `/usr/local` by default). By default this means that the configuration file will be +found in `/usr/local/etc/open5gs/msaf.yaml`. + +The location of the configuration file can be overridden at run-time by using the `-c` command line parameter with the +`open5gs-msafd` command, for example: + +```bash +/usr/local/bin/open5gs-msafd -c local-5gmsaf-config.yaml +``` + +## Configuration File Format + +The configuration file is written in [YAML](https://yaml.org/) 1.1 file format. + +Various settings in the file control things like logging output, listening and connection addresses, details of associated 5GMSd +Application Servers and other presets. + +### Notation + +Throughout this documentation we refer to the location of these configuration properties using a '`.`' separated path. Where a property name contains a `.` character it will be quoted using double quotes. For eaxmple, take the following snippet of YAML: + +```yaml +YAML: + files contain: + - version 1.1: textual value +``` + +We would refer to the field holding the value '`textual value`' as `YAML.files contain."version 1.1"`. + +### Configuration Structure + +The following are the properties in the 5GMSd Application Function configuration file and typical/default values: + +```yaml +logging: + level: info + domain: msaf + +sbi: + server: + no_tls: true + client: + no_tls: true + +msaf: + open5gsIntegration: false + sbi: + - addr: 0.0.0.0 + port: 7778 + m1: # Added in v1.2.0 + - addr: 0.0.0.0 # Added in v1.2.0 + port: 7778 # Added in v1.2.0 + m5: # Added in v1.2.0 + - addr: 0.0.0.0 # Added in v1.2.0 + port: 7778 # Added in v1.2.0 + maf: # Added in v1.2.0 + - addr: 127.0.0.25 # Added in v1.2.0 + port: 7777 # Added in v1.2.0 + applicationServers: + - canonicalHostname: localhost + urlPathPrefixFormat: /m4d/provisioning-session-{provisioningSessionId}/ + m3Host: localhost # Added in v1.4.0 + m3Port: 7777 # Added in v1.1.0 + certificate: examples/CertificatesIndex.json # Removed in v1.2.0 + contentHostingConfiguration: examples/ContentHostingConfiguration.json # Removed in v1.2.0 + provisioningSessionId: 12345678-9abc-def0-123456789abc # Removed in v1.1.0 + certificateManager: /usr/local/libexec/rt-5gms/af/self-signed-certmgr # Added in v1.2.0 + serverResponseCacheControl: # Added in v1.2.0 + - maxAge: 60 # Added in v1.2.0 + m1ProvisioningSessions: 60 # Added in v1.2.0 + m1ContentHostingConfigurations: 60 # Added in v1.2.0 + m1ServerCertificates: 60 # Added in v1.2.0 + m1ContentProtocols: 86400 # Added in v1.2.0 + m5ServiceAccessInformation: 60 # Added in v1.2.0 + dataCollectionDir: /usr/local/var/log/open5gs/reports # Added in v1.4.0 + offerNetworkAssistance: false # Added in v1.4.0 + networkAssistance: # Added in v1.4.0 + deliveryBoost: # Added in v1.4.0 + minDlBitRate: 1 Mbps # Added in v1.4.0 + boostPeriod: 30 # Added in v1.4.0 + +nrf: + sbi: + - addr: + - 127.0.0.10 + - ::1 + port: 7777 + +bsf: + notificationListener: # Added in v1.4.0 + - addr: + - 127.0.0.99 + port: 7779 + +parameter: + no_ipv4: false + no_ipv6: false + prefer_ipv4: false + +time: + nf_instance: + heartbeat: 0 + message: + duration: 10000 + +``` + +### Referencing other files + +The configuration file may also reference other files. If such a reference is made then the reference is either an absolute path or a relative path to file. If it is a relative path then it is relative to the location of the configuration file. + +**Warning: Be careful when moving a `msaf.yaml` configuration file to a different directory in the filesystem as any relative +pathed properties will no longer point to the correct location and will either need to be changed or the referenced files will also need to be moved too to maintain their relative paths.** + +The following properties may optionally contain relative paths: +- `msaf.certificates` - This is the JSON certificates index, see [Certificates Index](#certificates-index) for more details. +- `msaf.contentHostingConfiguration` - This is a ContentHostingConfiguration JSON object used to configure the 5GMSd Application + Server, see [ContentHostingConfiguration file](#contenthostingconfiguration-file) for more details. + +## Configuration Properties + +This section lists the properties in the configuration file, their use and valid values. + +### Logging + +**Location(s):** `logging.level` and `logging.domain` + +#### Logging Level + +The `logging.level` indicates the minimum level of logging messages that will be output. The default is `info`. + +Allowable values are: `trace`, `debug`, `info`, `warn`, `error`, `fatal` and `none` + +When `logging.domain` is also set, then this setting only affects the minimum logging level for the listed domains. + +#### Logging Domain + +The `logging.domain` property limits the affect of the `logging.level` property. This contains a comma separated list of domains. + +Domains relevant to the 5GMSd Application Function are: +- `msaf` - 5GMSd Application Function specific logging +- `sbi` - Open5GS SBI library functions for Client/Server operations. +- `app` - Open5GS App library functions for generic Open5GS application routines. +- `core` - Open5GS Core functions (e.g. low level socket handling, textual parsing and formatting, and memory management routines). + +#### Suggested Logging Configurations + +To reduce logging to warnings, errors and fatal messages only: + +```yaml +logging: + level: warn +``` + +To stop all logging: + +```yaml +logging: + level: none +``` + +To turn debugging output on for the 5GMSd Application Function: + +```yaml +logging: + level: debug + domain: msaf +``` + +### SBI interface security + +**Location(s):** `sbi.server.no_tls`, `sbi.server.cacert`, `sbi.server.key`, `sbi.server.cert`, `sbi.client.no_tls`, `sbi.client.cacert`, `sbi.client.key` and `sbi.client.cert` + +The `sbi.server.no_tls` indicates whether TLS should be configured for SBI server listening sockets. If `false` then no TLS is configured and the `sbi.server.cacert`, `sbi.server.key` and `sbi.server.cert` properties are ignored. If the `sbi.server.no_tls` property is `true` then the server will use: +- `sbi.server.cacert` is the filename of a file containing a CA bundle, in PEM format, to use to authenticate client public certificates. +- `sbi.server.key` is the filename of the private key, in PEM format, which is used for TLS connections for server sockets. +- `sbi.server.cert` is the filename of the public certificate, in PEM format, that will be presented as server authentication for TLS connections for server sockets. + +The `sbi.client.no_tls` indicates whether TLS should be configured for outgoing client requests to other NFs. If `false` then no TLS is configured and the `sbi.client.cacert`, `sbi.client.key` and `sbi.client.cert` properties are ignored. If the `sbi.client.no_tls` property is `true` then outgoing client requests will use: +- `sbi.client.cacert` is the filename of a file containing a CA bundle, in PEM format, to use to authenticate the server certificate presented by the remote NF. +- `sbi.client.key` is the filename of a private key, in PEM format, to use for encrypting the client communications. +- `sbi.client.cert` is the filename of the public certificate, in PEM format, to use for authenticating the client with the NF. + +### Open5GS integration + +**Location(s):** `msaf.open5gsIntegration` + +This is a boolean value (`true` or `false`) which indicates whether or not the 5GMSd Application Function will attempt to register +with a 5G Core, specifically the NRF. + +If this value is `true` then the `nrf` properties will describe the connection information for the NRF to register with. See +[NRF Connection](#nrf-connection) for more details. + +This is required to be `true` if you wish to use the Network Assistance or Dynamic Policies features. + +### SBI and default Interface Listening Address + +**Location(s):** `msaf.sbi.addr` and `msaf.sbi.port` + +The listening IP address is set in `msaf.sbi.addr` and the TCP port number is set in `msaf.sbi.port`. + +This address is used for SBI communications with other 5G Core Network Functions. It is also the default address for M1, M5 and +Management interfaces if they are not explicitly set in the configuration. + +### M1 Interface Listening Address + +**Location(s):** `msaf.m1.addr` and `msaf.m1.port` +**Version:** v1.2.0 and above + +The listening IP address is set in `msaf.m1.addr` and the TCP port number is set in `msaf.m1.port`. + +This is the communication address for external Application Service Providers to configure their services via the interface at +reference point M1. + +### M5 Interface Listening Address + +**Location(s):** `msaf.m5.addr` and `msaf.m5.port` +**Version:** v1.2.0 and above + +The listening IP address is set in `msaf.m5.addr` and the TCP port number is set in `msaf.m5.port`. + +This is the communication address for the 5GMSd Aware Application on the User Equipment implementing the interface at reference +point M5. + +### 5GMS AF Management Interface Listening Address + +**Location(s):** `msaf.maf.addr` and `msaf.maf.port` +**Version:** v1.2.0 and above + +The listening IP address is set in `msaf.maf.addr` and the TCP port number is set in `msaf.maf.port`. + +This is a communication interface for local 5GMSd Application Function management. This is not specified in TS 26.512 and is an +extra interface for this implementation. This should always be listening on a secure network, e.g. localhost only. + +### Application Servers + +**Location(s):** `msaf.applicationServers` + +This property is a list of associated 5GMSd Application Servers. Each entry in the list must contain `canonicalHostname`, +`urlPathPrefixFormat` and `m3Port` (since v1.1.0) properties. + +The `canonicalHostname` is the hostname or IP address of the Application Server. This is used to generate `mediaPlayerEntry` URLs for the ServiceAccessInformation objects available at interface M5 if no `domainNameAlias` is given in the ContentHostingConfiguration. From v1.1.0 of the Application Function, this is also the address that the Application Function will use for interface M3 communication with the Application Server. + +The `urlPathPrefixFormat` is a template string that is used to set the first part of the URL path for distributions from the Application Server at interface M4. Where the template contains `{provisioningSessionId}` will be replaced by the provisioning session Id that is associated with the ContentHostingConfiguration. + +The host name which is used for contacting the Application Server on the interface at M3 will be the `canonicalHostname` unless an `m3Host` property is defined for the application server, in which case the value of `m3Host` will be used as the host name to contact the Application Server at. + +The TCP port at which the Application Server interface at M3 is listening is defined by the `m3Port` property. The combination of `canonicalHostname` or `m3Host` and `m3Port` identifies the connection address that the Application Function will use. This property is only available from v1.1.0 onwards. + +Example: +```yaml +msaf: + applicationServers: + - canonicalHostname: ext-as.example.com + urlPathPrefixFormat: /{provisioningSessionId}/ + m3Host: localhost + m3Port: 7777 +``` + +### Data Collection (Consumption Reporting) + +**Location(s):** `msaf.dataCollectionDir` +**Versions:** v1.4.0 and above + +The Consumption Reporting feature uses a data collection directory to store sent reports in. The path for the data collection root can be set in `msaf.dataCollectionDir`. If not set then consumption reports are discarded after being received. There is no house-keeping for this directory, so an external house-keeping process must be used to free up disk space. + +### Network Assistance + +**Location(s):** `msaf.open5gsIntegration`, `msaf.offerNetworkAssistance`, `msaf.networkAssistance`, `nrf.sbi` and `bsf.notificationListener` +**Versions:** v1.4.0 and above + +The Network Assistance feature requires both `msaf.open5gsIntegration` and `msaf.offerNetworkAssistance` to be `true` (or `yes`) to activate. The `nrf` settings must also point to a valid NRF NF, and will be used to find a BSF and/or the PCF which is handling the policies for the UE. The `bsf.notificationListener` sets the address and optional port that will be used to listen for BSF notifications. + +When active, this feature will be advertised as available via the Service Access Information objects returned from requests at interface M5. + +The Delivery Boost Network Assistance feature will request a guaranteed minimum bit rate for a period of time on behalf of the client. The minimum bit rate used and the period of time are both configurable by setting the values for `msaf.networkAssistance.deliveryBoost.minDlBitRate` and `msaf.networkAssistance.deliveryBoost.boostPeriod` respectively. The `msaf.networkAssistance.deliveryBoost.minDlBitRate` must be expressed as a BitRate string according to TS 29.571, this is a decimal number followed by the bit rate units (`bps`, `Kbps`, `Mbps`, `Gbps` or `Tbps`), e.g. "0.5 Mbps" or "60 Kbps". The `msaf.networkAssistance.deliveryBoost.boostPeriod` is the integer number of seconds the boost will be activated for. These default to 1 Mbps for 30 seconds. + +Example of active Network Assistance: +```yaml +msaf: + open5gsIntegration: yes + offerNetworkAssistance: yes + networkAssistance: + deliveryBoost: + minDlBitRate: 1 Mbps + boostPeriod: 30 + +nrf: + sbi: + - addr: 127.0.0.10 + port: 7777 + +bsf: + notificationListener: + - addr: 127.0.0.99 +``` + +### Dynamic Policies + +**Location(s):** `msaf.open5gsIntegration`, `nrf.sbi` and `bsf.notificationListener` +**Versions:** v1.4.0 and above + +This feature requires the `msaf.open5gsIntegration` to be `true` (or `yes`) and the `nrf` settings to point to a valid NRF NF. The `bsf.notificationListener` sets the address and optional port that will be used to listen for BSF notifications. + +Example of active Network Assistance: +```yaml +msaf: + open5gsIntegration: yes + +nrf: + sbi: + - addr: 127.0.0.10 + port: 7777 + +bsf: + notificationListener: + - addr: 127.0.0.99 + port: 9000 +``` + +### ContentHostingConfiguration file + +**Note:** This setting is removed from v1.2.0 onwards + +**Location(s):** `msaf.contentHostingConfiguration` +**Version:** Up to and including v1.1, removed in v1.2.0 onwards + +The hosting configuration to use comes from a ContentHostingConfiguration JSON object held in an external file. The file-path to this JSON file is stored in the `msaf.contentHostingConfiguration` property using an absolute or relative (to the `msaf.yaml` configuration file) file-path. + +The ContentHostingConfiguration determines the configuration of the 5GMSd Application Server including which certificates and keys to send to the Application Server. + +### Certificates Index + +**Note:** This setting will be removed from v1.2.0 onwards + +**Location(s):** `msaf.certificates` +**Version:** Up to and including v1.1, removed in v1.2.0 onwards + +To test the distribution of media via secure HTTPS, the 5GMSd Application Function (and at runtime the 5GMSd Application Server which +will provide the hosting of the media) needs to be configured with one or more private key and public certificate pairs that can be +referenced from the ContentHostingConfiguration. + +To provide this configuration the 5GMSd Application Function, an index file is used to map certificateId values to a file containing the private key, public certificate and optionally any intermediate CA public certificates, all in PEM format. The index file itself contains a JSON object where the keys are the certificateIds as found in the COntentHostingConfiguration files and the values are the relative (to the index file) or absolute path to the PEM file. + +The filename of this JSON index file is stored in the `msaf.certificates` property of the `msaf.yaml` configuration file as a relative (to the configuration file) or absolute path. + +For a utility to quickly generate self-signed test certificates for a configuration please see the section below on [Generating Test Certificates](#generating-test-certificates). + +### Provisioning Session Id + +**Note:** This setting is removed from v1.1.0 onwards + +**Location(s):** `msaf.provisioningSessionId` +**Version:** Up to and including v1.0, removed in v1.1.0 onwards + +This setting provides the ProvisioningSessionId to use for MVP#2. This is here so that the Application Function and Application +Server can be synchronised with the same identifier in their respective configurations. + +This is the only ProvisioningSessionId the MVP#2 5GMSd Application Function will use. + +### Certificate Manager Program + +**Location(s):** `msaf.certificateManager` +**Version:** From version v1.2.0 onwards + +This is the path of an external program that can manage certificates and request signing of certificates. The example certificate +manager program will produce simple self signed certificates and will be the default certificate manager program set in the +installed configuration. + +The Certificate Manager program follows the "External Certificate Management" specification from the ["Implement M1 Server Certificates Provisionign API" issue on github](https://github.com/5G-MAG/rt-5gms-application-function/issues/17). + +### Default caching ages + +**Location(s):** `msaf.serverResponseCacheControl.maxAge`, `msaf.serverResponseCacheControl.m1ProvisioningSessions`, + `msaf.serverResponseCacheControl.m1ContentHostingConfigurations`, + `msaf.serverResponseCacheControl.m1ServerCertificates`, `msaf.serverResponseCacheControl.m1ContentProtocols`, + `msaf.serverResponseCacheControl.m5ServiceAccessInformation` +**Version:** From version v1.2.0 onwards + +These configuration values give the caching time in seconds signalled with responses in the different interfaces. + +| Parameter | Purpose | +| --- | --- | +| `maxAge` | The default `max-age` caching value. | +| `m1ProvisioningSessions` | The `max-age` for responses for the M1 ProvisioningSessions API. | +| `m1ContentHostingConfigurations` | The `max-age` for responses for the M1 ContentHostingProvisioning API. | +| `m1ServerCertificates` | The `max-age` for responses for the M1 ServerCertificatesProvisioning API. | +| `m1ContentProtocols` | The `max-age` for responses for the M1 ContentProtocolsDiscovery API. | +| `m5ServiceAccessInformation` | The `max-age` for responses for the M5 ServiceAccessInformation API. | + +## Generating Test Certificates + +**Note:** These instructions are not needed from v1.2.0 onwards as certificates are dynamically generated +and signed. + +To make the generation of certificates easier for testing, a script is available in the `~/rt-5gms-application-function/subprojects/rt-common-shared/5gms/scripts/make_self_signed_certs.py` which will generate an appropriate set of self-signed test certificates. This script requires the `python3` and `openssl` commands to be present, and the Python 3 YAML module. The script executes in the `python3` environment and uses the `openssl` command to generate the PEM certificate and private key file. + +If `openssl`, `python3` or Python3 yaml module are not already installed then they can be installed from your system package manager, for example: + +**Ubuntu/Debian and deviratives** +```bash +sudo apt -y install openssl python3 python3-yaml +``` + +**RedHat/CentOS/Fedora/Rocky and derivatives** +```bash +sudo dnf -y install openssl python3 python3-pyyaml +``` + +The `make_self_signed_certs.py` script takes either an Application Function configuration file path or two command line parameters, the first is the file-path for a ContentHostingConfiguration JSON file representing the output of the Application Function and the +second is the file-path of a certificates index JSON file. When using this script with the Application Function it is easier to use +the former command syntax. + +The script will examine the Application Function configuration file and extract the ContentHostingConfiguration. This is then examined for the certificateIds that are referenced and will create the private key and public certificate in PEM format at the file-path referenced from the certificates index JSON file. The generated certificates are self-signed, valid for 30 days and will include the `canonicalHostame` from the AF configuration and any `domainNameAlias` values from the ContentHostingConfiguration as Subject Alternative Names for the generated certificates. + +For example: + +```bash +~/rt-5gms-application-function/subprojects/rt-common-shared/5gms/scripts/make_self_signed_certs.py \ + --af-conf=/usr/local/etc/open5gs/msaf.yaml +``` diff --git a/pages/5g-media-streaming/tutorials/end-to-end.md b/pages/5g-media-streaming/tutorials/end-to-end.md index b07a66aa..23b7b85d 100644 --- a/pages/5g-media-streaming/tutorials/end-to-end.md +++ b/pages/5g-media-streaming/tutorials/end-to-end.md @@ -69,7 +69,7 @@ msaf: As we installed the AF as a local user, we start it with the following command: ```` -~/usr/local/bin/open5gs-msafd +/usr/local/bin/open5gs-msafd ```` #### Creating a content hosting configuration diff --git a/pages/5g-multicast-broadcast-services/specifications.md b/pages/5g-multicast-broadcast-services/specifications.md index 306c816c..787ed445 100644 --- a/pages/5g-multicast-broadcast-services/specifications.md +++ b/pages/5g-multicast-broadcast-services/specifications.md @@ -5,6 +5,12 @@ parent: 5G Multicast Broadcast Services has_children: false nav_order: 0 --- -# 📑 Specifications and relevant references -* Information about relevant specifications can be found at the [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/5G-Multicast-Broadcast-Services-(5MBS):-Relevant-Specifications) -* A list of relevant 3GPP Work Items can be found at [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/5G-Multicast-Broadcast-Services-(5MBS):-Relevant-Work-Items) +# 5G Multicast Broadcast Services +## 📑 Specifications and relevant references +* Information about relevant specifications can be found in this [page](https://5g-mag.github.io/Standards/pages/5g-multicast-broadcast-services/5g-multicast-broadcast-services-specifications.html) + +## 📑 Relevant Work Items +* A list of relevant 3GPP Work Items can be found in this [page](https://5g-mag.github.io/Standards/pages/5g-multicast-broadcast-services/5g-multicast-broadcast-services-workitems.html) + +## 📑 Guidelines and Profiles +* A quick guide on MBS Broadcast RAN Procedure can be found in this [page](https://5g-mag.github.io/Standards/pages/5g-multicast-broadcast-services/mbs-broadcast-RAN.html) diff --git a/pages/emergency-alerts/repositories.md b/pages/emergency-alerts/repositories.md index 4f622e8e..85084ed6 100644 --- a/pages/emergency-alerts/repositories.md +++ b/pages/emergency-alerts/repositories.md @@ -7,3 +7,6 @@ nav_order: 3 --- # ⭐ Related repositories + +## 5G Broadcast Transmitter for QRD and CRD (with support for Emergency Alerts): [rt-mbms-tx-for-qrd-and-crd](https://github.com/5G-MAG/rt-mbms-tx-for-qrd-and-crd/tree/emergency-alerts) +* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-mbms-tx-for-qrd-and-crd/tree/emergency-alerts/README.md) diff --git a/pages/lte-based-5g-broadcast/quick-start-guide.md b/pages/lte-based-5g-broadcast/quick-start-guide.md index ccf08c0a..34dbebd1 100644 --- a/pages/lte-based-5g-broadcast/quick-start-guide.md +++ b/pages/lte-based-5g-broadcast/quick-start-guide.md @@ -11,7 +11,7 @@ nav_order: 0 ## Setup Resources * [Hardware, OS & SDR Requirements](hardware-requirements.md) * [Sample Files](sample-files.md) -* [Service Announcement Formats](https://github.com/5G-MAG/rt-common-shared/wiki/MBMS-Service-Announcement-Files) +* [Service Announcement Formats](rt-common-shared/MBMS-service-announcement-files.md) ## Preparation After each reboot of your machine run: diff --git a/pages/lte-based-5g-broadcast/repositories.md b/pages/lte-based-5g-broadcast/repositories.md index 302f23b3..5fb6c477 100644 --- a/pages/lte-based-5g-broadcast/repositories.md +++ b/pages/lte-based-5g-broadcast/repositories.md @@ -24,6 +24,10 @@ nav_order: 3 * [Releases](https://github.com/5G-MAG/rt-mbms-mw/releases) * [Docker](https://github.com/5G-MAG/rt-mbms-mw/tree/development/middleware) +## MBMS Middleware for Android: [rt-mbms-mw-android](https://github.com/5G-MAG/rt-mbms-mw-android) +* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-mbms-mw-android#readme) +* [Releases](https://github.com/5G-MAG/rt-mbms-mw-android/releases) + ## Tools common to various projects: [rt-common-shared](https://github.com/5G-MAG/rt-common-shared) * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-common-shared#readme) diff --git a/pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md b/pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md new file mode 100644 index 00000000..c9f6adab --- /dev/null +++ b/pages/lte-based-5g-broadcast/rt-common-shared/MBMS-service-announcement-files.md @@ -0,0 +1,535 @@ +--- +layout: default +title: MBMS Service Announcement Files +parent: Tutorials +grand_parent: MBMS and LTE-based 5G Broadcast +has_children: false +nav_order: 0 +--- + +# MBMS Service Announcement Files + +The `ServiceAnnouncement(SA)` file also referred to as `bootstrap.multipart` in the context of 5G-MAG Reference Tools contains important information about the available broadcast and unicast streams. The 5G-MAG Reference Tools support three main formats. The target format needs to be configured before starting the `rt-mbms-mw` process as an automated format detection at runtime is currently not supported. + +Examples of the different SA formats can be found in the [rt-common-shared project](https://github.com/5G-MAG/rt-common-shared/tree/feature/mbms/mbms/bootstrap_examples). + +## Configuration of the format +The target format can directly be set in `/etc/5gmag-rt.conf` file: + +```` +mw: { + bootstrap_format: "" +} +```` + +Possible values are: +* `default`: Format used for the original implementation of seamless switching +* `5gmag_bc_uc`: Format agreed on by 5G-MAG while reviewing the `default` format +* `5gmag_legacy`: Format used for the sample recordings + +## Default format +The default format is the one that was used for the original seamless switching implementation implemented in close coordination between ORS and Rohde&Schwarz: + +```` +MIME-Version: 1.0 +Content-Type: multipart/related; boundary="++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++--"; type="application/mbms-envelope+xml" +Content-Description: LTE MBMS Service Announcement + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-envelope+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///envelope.xml + + + + + + + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/sdp +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.sdp + +v=0 +o=ROHDE-SCHWARZ-BSCC 269087077 1634036383 IN IP4 11.11.11.11 +s=HLS Streaming Session 0x1009f165 +i=File Download Session +t=3843025183 4789105183 +a=mbms-mode:broadcast-mbsfn 269087077 +c=IN IP4 238.1.1.111/127 +b=AS:2000 +m=application 40101 FLUTE/UDP 0 +a=flute-tsi:0 +a=flute-ch:1 +a=3GPP-QoE-Metrics:metrics={Object_Loss};rate=null;resolution=10 +a=3GPP-QoE-Metrics:metrics={Network_Resource};rate=null;resolution=10 + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.m3u8 + +#EXTM3U +#EXT-X-VERSION:6 +#EXT-X-STREAM-INF:BANDWIDTH=2305600,RESOLUTION=1280x720,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_0.m3u8 + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: http://localhost:3333/watchfolder/hls/manifest.m3u8 + +#EXTM3U +#EXT-X-VERSION:6 +#EXT-X-STREAM-INF:BANDWIDTH=2305600,RESOLUTION=1280x720,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_0.m3u8 +#EXT-X-STREAM-INF:BANDWIDTH=1205600,RESOLUTION=960x540,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_1.m3u8 + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-user-service-description+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///usdBundle.xml + + + + 1 + + BSCC Service1 + BSCC Dienst1 + EN-GB + DE-DE + + 23 + 27 + + + 0 + + file:///TMGI-0x1009f165.m3u8 + 2 + + + http://localhost:3333/watchfolder/hls/stream_0.m3u8 + + 0 + + + + file:///TMGI-0x1009f165.m3u8 + http://localhost:3333/watchfolder/hls/stream_1.m3u8 + + + file:///TMGI-0x1009f165.m3u8 + http://localhost:3333/watchfolder/hls/stream_0.m3u8 + + + + file:///TMGI-0x1009f165schedule.xml + + 0 + + + 2 + + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-schedule+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165schedule.xml + + + + 1 + + + 2021-10-12T10:59:43Z + 2051-10-05T10:59:43Z + 0 + 0 + 0 + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +```` + + +## 5G-MAG BC_UC format +This format represents a revised version of the default format: + +```` +MIME-Version: 1.0 +Content-Type: multipart/related; boundary="++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++--"; type="application/mbms-envelope+xml" +Content-Description: LTE MBMS Service Announcement + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-envelope+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///envelope.xml + + + + + + + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/sdp +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.sdp + +v=0 +o=ROHDE-SCHWARZ-BSCC 269087077 1634036383 IN IP4 11.11.11.11 +s=HLS Streaming Session 0x1009f165 +i=File Download Session +t=3843025183 4789105183 +a=mbms-mode:broadcast-mbsfn 269087077 +c=IN IP4 238.1.1.111/127 +b=AS:2000 +m=application 40101 FLUTE/UDP 0 +a=flute-tsi:0 +a=flute-ch:1 +a=3GPP-QoE-Metrics:metrics={Object_Loss};rate=null;resolution=10 +a=3GPP-QoE-Metrics:metrics={Network_Resource};rate=null;resolution=10 + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.m3u8 + +#EXTM3U +#EXT-X-VERSION:6 +#EXT-X-STREAM-INF:BANDWIDTH=2305600,RESOLUTION=1280x720,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_0.m3u8 + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: http://localhost:3333/watchfolder/hls/manifest.m3u8 + +#EXTM3U +#EXT-X-VERSION:6 +#EXT-X-STREAM-INF:BANDWIDTH=2305600,RESOLUTION=1280x720,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_0.m3u8 +#EXT-X-STREAM-INF:BANDWIDTH=1205600,RESOLUTION=960x540,FRAME-RATE=25.000,CODECS="avc1.64001f,mp4a.40.2" +stream_1.m3u8 + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-user-service-description+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///usdBundle.xml + + + + 1 + + BSCC Service1 + BSCC Dienst1 + EN-GB + DE-DE + + 23 + 27 + + + 0 + + stream_0.m3u8 + 2 + + + http://localhost:3333/watchfolder/hls/stream_0.m3u8 + http://localhost:3333/watchfolder/hls/stream_1.m3u8 + + 0 + + + + stream_0.m3u8 + http://localhost:3333/watchfolder/hls/stream_1.m3u8 + + + stream_0.m3u8 + http://localhost:3333/watchfolder/hls/stream_0.m3u8 + + + + file:///TMGI-0x1009f165schedule.xml + + 0 + + + 2 + + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +Content-Type: application/mbms-schedule+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165schedule.xml + + + + 1 + + + 2021-10-12T10:59:43Z + 2051-10-05T10:59:43Z + 0 + 0 + 0 + + + +--++++++++++++++++++++++++Rohde&Schwarz-BSCC++++++++++++++++++++++++-- +```` + +## 5G-MAG Legacy format +5G-MAG provides multiple [sample recordings](https://github.com/5G-MAG/Documentation-and-Architecture/wiki/Sample-Files) captured and hosted by ORS. These files were recorded at the start of the project and require a specific format of the ServiceAnnouncement file: + +```` +MIME-Version: 1.0 +Content-Type: multipart/related; boundary="xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx--"; type="application/mbms-envelope+xml" +Content-Description: LTE MBMS Service Announcement + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/mbms-envelope+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///envelope.xml + + + + + + + + + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/sdp +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.sdp + +v=0 +o=ROHDE-SCHWARZ-BSCC 269087077 1630568733 IN IP4 11.11.11.11 +s=HLS Streaming Session 0x1009f165 +i=File Download Session +t=3839557533 4785637533 +a=mbms-mode:broadcast-mbsfn 269087077 +c=IN IP4 238.1.1.111/127 +b=AS:1699 +m=application 40101 FLUTE/UDP 0 +a=flute-tsi:16 +a=flute-ch:1 +a=3GPP-QoE-Metrics:metrics={Object_Loss};rate=null;resolution=10 +a=3GPP-QoE-Metrics:metrics={Network_Resource};rate=null;resolution=10 + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165.m3u8 + +#EXTM3U +#EXT-X-VERSION:3 + +#EXT-X-STREAM-INF:CODECS="avc1.4D401E,mp4a.40.2",BANDWIDTH=1427133,FRAME-RATE=25.000,RESOLUTION=640x360 +out/u/bbb/qxa/manifest_3.m3u8?m=1614073235 + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/vnd.apple.mpegurl +Content-Transfer-Encoding: 7bit +Content-Location: http://10.160.82.131/out/u/bbb/qxa/manifest.m3u8 + +#EXTM3U +#EXT-X-VERSION:3 +#EXT-X-STREAM-INF:BANDWIDTH=3847133,AVERAGE-BANDWIDTH=3847133,RESOLUTION=1280x720,FRAME-RATE=25.000,CODECS="avc1.4D401F,mp4a.40.2" +manifest_1.m3u8?m=1614073235 +#EXT-X-STREAM-INF:BANDWIDTH=2857098,AVERAGE-BANDWIDTH=2857098,RESOLUTION=854x480,FRAME-RATE=25.000,CODECS="avc1.4D401E,mp4a.40.2" +manifest_2.m3u8?m=1614073235 +#EXT-X-STREAM-INF:BANDWIDTH=1427133,AVERAGE-BANDWIDTH=1427133,RESOLUTION=640x360,FRAME-RATE=25.000,CODECS="avc1.4D401E,mp4a.40.2" +manifest_3.m3u8?m=1614073235 + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/mbms-user-service-description+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///usdBundle.xml + + + + 1 + + Test Service TMGI-0x1009f165 + EN: Test Service TMGI-0x1009f165 + DE: Test Service TMGI-0x1009f165 + EN + DE + + 23 + 27 + + + 0 + + out/u/bbb/qxa/manifest_3.m3u8?m=1614073235 + file:///TMGI-0x1009f165.m3u8 + 2 + + 0 + + + + file:///TMGI-0x1009f165schedule.xml + + 0 + + + 2 + + + + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +Content-Type: application/mbms-schedule+xml +Content-Transfer-Encoding: 7bit +Content-Location: file:///TMGI-0x1009f165schedule.xml + + + + 1 + + + 2021-09-02T07:45:33Z + 2051-08-26T07:45:33Z + 0 + 0 + 0 + + + +--xxx.yyy.zzz.--Rohde&Schwarz-BSCC--zzz.yyy.xxx-- +```` diff --git a/pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md b/pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md new file mode 100644 index 00000000..e6c34243 --- /dev/null +++ b/pages/lte-based-5g-broadcast/rt-mbms-modem/GPS-time-synchronization.md @@ -0,0 +1,63 @@ +--- +layout: default +title: GPS Time Synchonization for rt-mbms-modem +parent: Tutorials +grand_parent: MBMS and LTE-based 5G Broadcast +has_children: false +nav_order: 0 +--- + +# GPS Time Synchonization for rt-mbms-modem + +Preconditions: install, configure and enable ``gpsd`` by +following [this guide.](https://github.com/5G-MAG/rt-mbms-modem#measurement-recording-and-gps) + +## Install chrony + +```` +sudo apt install chrony +```` + +## Edit ``/etc/chrony/chrony.conf``, and add the following line at the end: + +```` +refclock SHM 0 delay 0.5 refid NMEA +```` + +## Edit ``/etc/default/gpsd``, and add options '-n -b': + +```` +# Devices gpsd should collect to at boot time. +# They need to be read/writeable, either by user gpsd or the group dialout. +DEVICES="/dev/ttyACM0" +# Other options you want to pass to gpsd +GPSD_OPTIONS="-n -b" +```` + +## Restart gpsd and chrony: + +```` +sudo systemctl restart gpsd +sudo systemctl restart chrony +```` + +## Done! + +You can check if chrony receives time data from your GPS devices with ``chronyc sources`` + +After around 30 seconds, you should see last sample data in the NMEA line, e.g: + +```` +210 Number of sources = 9 +MS Name/IP address Stratum Poll Reach LastRx Last sample +=============================================================================== +#- NMEA 0 4 377 11 +73ms[ +73ms] +/- 251ms +^- pugot.canonical.com 2 6 377 53 +394us[ +394us] +/- 54ms +^+ chilipepper.canonical.com 2 6 377 54 +156us[ +185us] +/- 44ms +^- alphyn.canonical.com 2 6 377 52 +624us[ +624us] +/- 127ms +^+ golem.canonical.com 2 6 377 55 +324us[ +352us] +/- 53ms +^+ extern4.nemox.net 2 6 377 54 -177us[ -149us] +/- 48ms +^+ 194.112.182.172 2 6 377 55 -151us[ -123us] +/- 29ms +^* ntp.candystore.at 2 6 377 53 +132us[ +160us] +/- 23ms +^+ svn.mediainvent.at 2 6 377 55 -94us[ -66us] +/- 36ms +```` diff --git a/pages/lte-based-5g-broadcast/specifications.md b/pages/lte-based-5g-broadcast/specifications.md index b4ea0397..1efb71be 100644 --- a/pages/lte-based-5g-broadcast/specifications.md +++ b/pages/lte-based-5g-broadcast/specifications.md @@ -5,6 +5,10 @@ parent: MBMS and LTE-based 5G Broadcast has_children: false nav_order: 0 --- -# 📑 Specifications and relevant references -* Information about relevant specifications can be found at the [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/MBMS-&-LTE-based-5G-Broadcast:-Relevant-Specifications) -* A list of relevant 3GPP Work Items can be found at [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/MBMS-&-LTE-based-5G-Broadcast:-Relevant-Work-Items) + +# MBMS and LTE-based 5G Broadcast +## 📑 Specifications and relevant references +* Information about relevant specifications can be found in this [page](https://5g-mag.github.io/Standards/pages/lte-based-5g-broadcast/lte-based-5g-broadcast-specifications.html) + +## 📑 Relevant Work Items +* A list of relevant 3GPP Work Items can be found in this [page](https://5g-mag.github.io/Standards/pages/lte-based-5g-broadcast/lte-based-5g-broadcast-workitems.html) diff --git a/pages/xr-media-integration-in-5g/repositories.md b/pages/xr-media-integration-in-5g/repositories.md index b247e733..841459a5 100644 --- a/pages/xr-media-integration-in-5g/repositories.md +++ b/pages/xr-media-integration-in-5g/repositories.md @@ -2,7 +2,7 @@ layout: default title: Repositories parent: XR Media Integration in 5G -has_children: false +has_children: true nav_order: 3 --- @@ -19,11 +19,15 @@ See also: [xr-player-overview](tutorials/xr-player-overview) * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-gITFast#readme) * [Releases](https://github.com/5G-MAG/rt-xr-gITFast/releases) -## Media pipelines factory and plugins implementing the MAF API: [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native) +## Media pipelines factory and plugins implementing the Media Access Function (MAF) API: [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native) * [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-maf-native#readme) * [Releases](https://github.com/5G-MAG/rt-xr-maf-native/tags) -## Test content: [rt-xr-content](https://github.com/5G-MAG/rt-xr-content) +## Media Access Function (MAF) API Unity3D packager: [rt-xr-maf-plugin](https://github.com/5G-MAG/rt-xr-maf-plugin) +* [Information and how to download, build, install and run](https://github.com/5G-MAG/rt-xr-maf-plugin#readme) +* [Releases](https://github.com/5G-MAG/rt-xr-maf-plugin/tags) + +## Content for the XR Unity Player: [rt-xr-content](https://github.com/5G-MAG/rt-xr-content) * [Information](https://github.com/5G-MAG/rt-xr-content#readme) * [Releases](https://github.com/5G-MAG/rt-xr-maf-native/tags) diff --git a/pages/xr-media-integration-in-5g/features.md b/pages/xr-media-integration-in-5g/repositories/featuresXRplayer.md similarity index 99% rename from pages/xr-media-integration-in-5g/features.md rename to pages/xr-media-integration-in-5g/repositories/featuresXRplayer.md index 9eda1b99..f8620fb6 100644 --- a/pages/xr-media-integration-in-5g/features.md +++ b/pages/xr-media-integration-in-5g/repositories/featuresXRplayer.md @@ -1,12 +1,13 @@ --- layout: default -title: Features -parent: XR Media Integration in 5G +title: Features XR Player +grand_parent: XR Media Integration in 5G +parent: Repositories has_children: false nav_order: 0 --- -## XR Player Features +## XR Unity Player Features ### Planned for v1.0.0 diff --git a/pages/xr-media-integration-in-5g/specifications.md b/pages/xr-media-integration-in-5g/specifications.md index 4b242d05..ef399a97 100644 --- a/pages/xr-media-integration-in-5g/specifications.md +++ b/pages/xr-media-integration-in-5g/specifications.md @@ -6,6 +6,9 @@ has_children: false nav_order: 0 --- -# 📑 Specifications and relevant references -* Information about relevant specifications can be found at the [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/XR-(eXtended-Reality):-Relevant-Specifications) -* A list of relevant 3GPP Work Items can be found at [Standards Wiki](https://github.com/5G-MAG/Standards/wiki/XR-(eXtended-Reality):-Relevant-Work-Items) +# eXtended Reality (XR) +## 📑 Specifications and relevant references +* Information about relevant specifications can be found in this [page](https://5g-mag.github.io/Standards/pages/xr/xr-specifications.html) + +## 📑 Relevant Work Items +* A list of relevant 3GPP Work Items can be found in this [page](https://5g-mag.github.io/Standards/pages/xr/xr-workitems.html) diff --git a/pages/xr-media-integration-in-5g/xr-player-overview.md b/pages/xr-media-integration-in-5g/tutorials/xr-player-overview.md similarity index 90% rename from pages/xr-media-integration-in-5g/xr-player-overview.md rename to pages/xr-media-integration-in-5g/tutorials/xr-player-overview.md index 6b8c07a6..d47cab66 100644 --- a/pages/xr-media-integration-in-5g/xr-player-overview.md +++ b/pages/xr-media-integration-in-5g/tutorials/xr-player-overview.md @@ -1,12 +1,13 @@ --- layout: default -title: XR Player project overview -parent: XR Media Integration in 5G +title: XR Player Project overview +grand_parent: XR Media Integration in 5G +parent: Tutorials has_children: false nav_order: 0 --- -# XR Player : project overview +# XR Unity Player: Project overview ## Scene description format @@ -14,7 +15,6 @@ The Scene Description format standardized by [ISO/IEC JTC 1/SC29/WG03](https://w It establishes interfaces like the Media Access Function (MAF) API to enable cross-platform interoperability, ensuring efficient retrieval and processing of media data, by decoupling the Presentation Engine from media pipeline. - ## XR Player implementation ![Alt text](../images/rt-xr-overview.jpg) @@ -25,16 +25,11 @@ The unity project builds on the following dependencies: * [rt-xr-glTFast](https://github.com/5G-MAG/rt-xr-gITFast): parsing and instantiating of 3D scenes in Unity. * [rt-xr-maf-native](https://github.com/5G-MAG/rt-xr-maf-native): a C++ Media Access Functions (MAF) API implementation, extensible with custom media pipeline plugins. - - - ### Test content * [rt-xr-content](https://github.com/5G-MAG/rt-xr-content): test content implementing the scene description format. - -See the [features page](features) for implementation status of the scene description format. - +See the [features page](../repositories/featuresXRplayer.md) for implementation status of the scene description format. ## MAF API & Media pipelines @@ -44,11 +39,8 @@ It's purpose is to decouple the presentation engine from media pipeline manageme - pass View informations to the media pipelines (eg. to optimize fetching media ) - read media buffers updated by the media pipelines - The MAF API is protocol and codec agnostic, media can be fetched a remote URL. - - ### Media player implementation #### MediaPlayer component diff --git a/pages/xr-media-integration-in-5g/tutorials/xr-player-win11-openXR.md b/pages/xr-media-integration-in-5g/tutorials/xr-player-win11-openXR.md index 55baffe9..3e2a68f9 100644 --- a/pages/xr-media-integration-in-5g/tutorials/xr-player-win11-openXR.md +++ b/pages/xr-media-integration-in-5g/tutorials/xr-player-win11-openXR.md @@ -1,13 +1,13 @@ --- layout: default -title: Using the XR Player on windows +title: XR Player on Windows parent: Tutorials grand_parent: XR Media Integration in 5G has_children: false -nav_order: 0 +nav_order: 1 --- - +## Introduction This tutorial covers usage of XR Player on Windows. 1. table of content @@ -21,13 +21,10 @@ The Meta Quest HMDs connected to a PC through Meta Quest Link provide such OpenX {: .highlight } If you do not have a Meta Quest HMD, simply ignore the requirements and optional steps related to Meta Quest in this tutorial. - - ## Requirements - Windows 11 - In order to use the Meta Quest link: {: .d-inline-block } optional @@ -102,4 +99,4 @@ pause ### Keyboard / Mouse controls -Refer to the github repository for the [up to date list of available keyboard and mouse controls](https://github.com/5G-MAG/rt-xr-unity-player?tab=readme-ov-file#usage). \ No newline at end of file +Refer to the github repository for the [up to date list of available keyboard and mouse controls](https://github.com/5G-MAG/rt-xr-unity-player?tab=readme-ov-file#usage).