Skip to content

Latest commit

 

History

History
267 lines (216 loc) · 14.4 KB

README.md

File metadata and controls

267 lines (216 loc) · 14.4 KB
Raw

5G-MAG Reference Tools: 5GMS Application Server - Development

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 <<EOF
[DEFAULT]
log_dir = /tmp/rt-5gms-as/logs
run_dir = /tmp/rt-5gms-as

### 5GMS Application Server specific configurations
[5gms_as]
log_level = info
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
m4d_path_prefix = /m4d/provisioning-session-{provisioningSessionId}/

### 5GMS Application Server nginx specific configuration
[5gms_as.nginx]
root_temp = /tmp/rt-5gms-as
EOF
mkdir -p /tmp/rt-5gms-as/cache
mkdir /tmp/rt-5gms-as/logs

Run the example directly:

cd ~/rt-5gms-application-server/src
python3 -m rt_5gms_as.app

This will start nginx with a default configuration that will respond with a 404 to any request on http://localhost:8080/.

At this point the 5GMS Application Server is ready for configuration by an M3 client such as the 5GMS Application Function or the m3_client_cli.py test script.

Testing with the Application Function

  1. Install both the 5GMS Application Server and Application Function.
  • To install the 5GMS Application Server follow either the sdist, direct from source or in a virtual environment instructions from the Installing section of the main README.
  • To install the 5GMS Application Function follow the directions to install the dependencies, retrieve, build and install the 5GMS Application Function from the 5GMS Application Function documentation.
  1. Configure the Application Function with the M3 port number of the Application Server (i.e. 7777) in the msaf.applicationServers section of the msaf.yaml file.
  • This is an example applicationServers entry from the msaf.yaml configuration file with the m3Port set.
    msaf:
        ...
        applicationServers:
          - canonicalHostname: localhost
            urlPathPrefixFormat: /m4d/provisioning-session-{provisioningSessionId}/
            m3Port: 7777
        ...
  1. In one terminal window, start the Application Server.
  • e.g. use the command 5gms-application-server
  1. In another terminal window, start the Application Function.
  • e.g. use the command ~/rt-5gms-application-function/install/bin/open5gs-msafd

The Application Function should then configure the Application Server using the Server Certificates and Content Hosting Configuration it has been configured with. This should be evident from log messages from the Application Server and Application Function and from the /tmp/rt_5gms_as.conf NGINX configuration.

See the 5GMS Application Function documentation for more details on configuring it with Certificates and a Content Hosting Configuration.

Testing without the Application Function

To enable debugging and testing, a simple M3 client command can be found the the tests subdirectory:

Usage:
    m3_client_cli.py -h | --help
    m3_client_cli.py -c | --certificate <connect>
    m3_client_cli.py -c | --certificate <connect> (add|update) <certificate-id> <pem-file>
    m3_client_cli.py -c | --certificate <connect> delete <certificate-id>
    m3_client_cli.py -H | --content-hosting-configuration <connect>
    m3_client_cli.py -H | --content-hosting-configuration <connect> (add|update) <provisioning-session-id> <content-hosting-configuration-json-file>
    m3_client_cli.py -H | --content-hosting-configuration <connect> delete <provisioning-session-id>
    m3_client_cli.py -H | --content-hosting-configuration <connect> purge <provisioning-session-id> [<pattern>]

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:

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 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 wiki page, then you would simply run the AS from the virtual environment using your local configuration file. For example:

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:

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" above).

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" 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:

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:

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):

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:

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:

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:

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.
    • 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.
    • 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/