byteblower-test-cases-docsis-atp 1.0.0

Perform traffic tests for DOCSIS 4.0 ATP using ByteBlower.

Introduction

This package contains an implementation of the DOCSIS 4.0 ATP Test using the ByteBlower Test Framework.

The goal of the test is to verify the DOCSIS PIE AQM behavior in the presence and absence of LLD traffic, and evaluate the delay estimator.

DOCSIS 4.0 ATP introduction

This ByteBlower MULPIv4 LL-04.40 Part test case allows you to:

1. Run tests based on MULPIv4 LL-04 ATP

2. Collect & Analyse statistics

3. Generate HTML report

For more detailed documentation, please have a look at Test Case: DOCSIS 4.0 ATP in the ByteBlower API documentation.

Installation

Requirements

• ByteBlower Test Framework: ByteBlower ® is a traffic generator/analyser system for TCP/IP networks.

• Highcharts-excentis: Used for generating graphs

• jinja2: To create HTML reports

Prepare runtime environment

We recommend managing the runtime environment in a Python virtual environment. This guarantees proper separation of the system-wide installed Python and pip packages.

Python

The ByteBlower Test Framework currently supports Python versions 3.7 up to 3.12.

Important: Working directory

All the following sections expect that you first moved to your working directory where you want to run this project. You may also want to create your configuration files under a sub-directory of your choice.

1. On Unix-based systems (Linux, WSL, macOS):

   cd '/path/to/working/directory'

2. On Windows systems using PowerShell:

   cd 'c:\path\to\working\directory'

Python virtual environment

Make sure to use the right Python version (>= 3.7, <= 3.11), list all Python versions installed in your machine by running:

1. On Windows systems using PowerShell:

   py --list

If no Python version is in the required range, you can download and install Python 3.7 or above using your system package manager or from https://www.python.org/ftp/python.

Prepare Python virtual environment: Create the virtual environment and install/update pip and build.

1. On Unix-based systems (Linux, WSL, macOS):

   Note: Mind the leading . which means sourcing ./.venv/bin/activate.

   python3 -m venv --clear .venv
   . ./.venv/bin/activate
   pip install -U pip build

2. On Windows systems using PowerShell:

   Note: On Microsoft Windows, it may be required to enable the Activate.ps1 script by setting the execution policy for the user. You can do this by issuing the following PowerShell command:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

   See About Execution Policies for more information.

   Make sure to specify the python version you’re using. For example, for Python 3.8:

   py -3.8 -m venv --clear .venv
   & ".\.venv\Scripts\activate.ps1"
   python -m pip install -U pip build

To install the ByteBlower DOCSIS 4.0 ATP test case and its dependencies, first make sure that you have activated your virtual environment:

1. On Unix-based systems (Linux, WSL, macOS):

   . ./.venv/bin/activate

2. On Windows systems using PowerShell:

   ./.venv/Scripts/activate.ps1

Then, run:

pip install -U byteblower-test-cases-docsis-atp

Quick start

Command-line interface

After providing the appropriate test setup and frame configurations, the test script can be run either as python module or as a command-line script.

For example (to get help for the command-line arguments):

1. As a python module:

   # To get help for the command-line arguments:
   python -m byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 --help

2. As a command-line script:

   # To get help for the command-line arguments:
   byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --help

To run the ByteBlower DOCSIS 4.0 ATP test case, you should first provide your test configuration file.

you can use the Configuration example as a reference. Make sure to update the example configuration to your actual setup configuration (ByteBlower server host name or IP, NSI and CPE ports)

part1.json is the default configuration file name. You can use the argument --config-file to specify your configuration file.

The reports will be stored under a subdirectory reports/.

1. On Unix-based systems (Linux, WSL, macOS):

   # Optional: create part1.json, then copy the configuration to it
   touch part1.json
   # Create reports folder to store HTML/JSON files
   mkdir reports
   # Run test
   byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --report-path reports

2. On Windows systems using PowerShell:

   # Optional: create part1.json, then copy the configuration to it
   New-Item part1.json
   # Create reports folder to store HTML/JSON files
   md reports
   # Run test
   byteblower-test-cases-docsis-atp-mulpi-v4-0-ll-04-40-part1 --report-path reports

Integrated

High-level integration with manual interaction:

from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 import run

# Defining test configuration, report path and report file name prefix:
test_config = {} # Here you should provide your test setup + frame(s') configuration(s)
report_path = 'my-output-folder' # Optional: provide the path to the output folder, defaults to the current working directory
report_prefix = 'my-dut-feature-test' # Optional: provide prefix of the output files, defaults to 'report'

# Run the DOCSIS 4.0 ATP test:
run(test_config, report_path=report_path, report_prefix=report_prefix)

High-level integration in user test scripts and optional custom post-processing:

from byteblower.test_cases.docsis_atp.mulpi_v4_0.ll_04_40.part1 import (
    configure_traffic_endpoints,
    generate_report,
    run_procedure_1_1,
    run_procedure_1_2,
)

_TEST_CONFIG = {
    "server": "byteblower-server.example.com",
    "nsi": {
        "name": "NSI",
        "interface": "nontrunk-1",
        "mac": "00:ff:bb:00:00:11",
        "ipv4": "dhcp"
    },
    "cpe": {
        "name": "CPE",
        "interface": "trunk-1-1",
        "mac": "00:ff:bb:00:00:22",
        "ipv4": "dhcp",
        "nat": True
    }
}

# 1. Configure the test
traffic_endpoints_configuration = configure_traffic_endpoints(_TEST_CONFIG)
#    + Extract the traffic endpoints for the two test procedures
server, nsi_config, cpe_config = traffic_endpoints_configuration

# NOTE: At this point, prepare the CMTS and cable modems
# for test procedure 1.1

# 2. Run LL-04.40 Part 1, test Procedure 1.1
proc_1_report_info = run_procedure_1_1(
    server,
    nsi_config,
    cpe_config,
    enable_capture=True,
    enable_sequence_numbers=True,
)

# NOTE: At this point, prepare the CMTS and cable modems
# for test procedure 1.2

# 3. Run LL-04.40 Part 1, test Procedure 1.2
proc_2_report_info = run_procedure_1_2(
    server,
    nsi_config,
    cpe_config,
    enable_capture=True,
    enable_sequence_numbers=True,
)

# 4. Generate the (HTML) test report
report_file_path = generate_report(
    proc_1_report_info,
    proc_2_report_info,
    report_path=Path.cwd(),
    report_prefix='my_report_prefix',
)

# 5. Extract captures and flow UDP ports for each test procedure
#    To be used for further post-processing
proc_1_capture_info = proc_1_report_info[2]
proc_1_capture_file_path, proc_1_udp_dest_ports = proc_1_capture_info

proc_2_capture_info = proc_2_report_info[2]
proc_2_capture_file_path, proc_2_udp_dest_ports = proc_2_capture_info

Configuration example

{
   "server": "byteblower-server.example.com",
   "nsi": {
      "name": "NSI",
      "interface": "nontrunk-1",
      "ipv4": "10.1.1.125",
      "netmask": "255.255.255.0",
      "gateway": "10.1.1.1"
   },
   "cpe": {
      "name": "CPE",
      "interface": "trunk-1-7",
      "ipv4": "dhcp",
      "nat": true
   }
}

More detailed documentation is available in the Configuration file section of the documentation.