# ETSI 5G NGAP and 5G NAS protocol project


## Introduction

This repositorie contains Abstract Test Suite (ATS) developed in TTCN-3 source code based on test specifications for ETSI 5G NGAP and 5G NAS conformance protocol testing, Release 16:
- [ETSI TS 103 920-1](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392001/) : "5G NGAP Conformance Testing for the N2 interface; Part 1: Protocol Implementation Conformance Statement (PICS) (version 1.2.1)"
- [ETSI TS 103 920-2](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392002/) : "5G NGAP Conformance Testing for the N2 interface; Part 2: Test Suite Structure (TSS) and Test Purposes (TP) (version 1.2.1)"
- [ETSI TS 103 920-3](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392003/) : "5G NGAP Conformance Testing for the N2 interface; Part 3: Abstract Test Suite (ATS) and partial Protocol Implementation eXtra Information for Testing (PIXIT) proforma specification (version 1.2.1)"
- [ETSI TS 103 921-1](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392101/) : "5G NAS Conformance Testing for the N1 interface; Part 1: Protocol Implementation Conformance Statement (PICS) (version 1.2.1)"
- [ETSI TS 103 921-2](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392102/) : "5G NAS Conformance Testing for the N1 interface; Part 2: Test Suite Structure (TSS) and Test Purposes (TP) (version 1.2.1)"
- [ETSI TS 103 921-3](https://www.etsi.org/deliver/etsi_ts/103900_103999/10392103/) : "5G NAS Conformance Testing for the N1 interface; Part 3: Abstract Test Suite (ATS) and partial Protocol Implementation eXtra Information for Testing (PIXIT) proforma specification (version 1.2.1)"

Following 3GPP library [Lib3GPP-IWD_23wk37](https://www.3gpp.org/ftp/tsg_ran/WG5_Test_ex-T1/TTCN/Deliveries/TTCN3/iwd-TTCN3-B2022-09_D23wk37.zip) was used. 

ETSI 5G NGAP and 5G NAS conformance test specifications are based on following base specifications:
- [ETSI TS 123 501](https://www.etsi.org/deliver/etsi_ts/123500_123599/123501/16.20.00_60/ts_123501v162000p.pdf): "5G; System architecture for the 5G System (5GS) (3GPP TS 23.501 version 16.20.0 Release 16)"
- [ETSI TS 123 502](https://www.etsi.org/deliver/etsi_ts/123500_123599/123502/16.19.00_60/ts_123502v161900p.pdf): "5G; Procedures for the 5G System (5GS) (3GPP TS 23.502 version 16.19.0 Release 16)"
- [ETSI TS 124 501](https://www.etsi.org/deliver/etsi_ts/124500_124599/124501/16.15.00_60/ts_124501v161500p.pdf): "5G; Non-Access-Stratum (NAS) protocol for 5G System (5GS); Stage 3 (3GPP TS 24.501 version 16.15.0 Release 16)"
- [ETSI TS 138 413](https://www.etsi.org/deliver/etsi_ts/138400_138499/138413/16.17.00_60/ts_138413v161700p.pdf): "5G; NG-RAN; NG Application Protocol (NGAP) (3GPP TS 38.413 version 16.17.0 Release 16)"


## Contact information

Email at `cti_support` at `etsi` dot `org`.

## License

Unless specified otherwise, the content of this repository and the files contained are released under the BSD-3-Clause license.
See the attached LICENSE file or visit https://forge.etsi.org/legal-matters.

## STFs/TTFs

The following STFs/TTFs were or are currently involved in the evolutions of the ETSI 5G NGAP and 5G NAS protocols project:
- TTF T033, TTF T041, TTF T048


# Installation

The NGAP/NAS Conformance Test System project builds and tests regularly on the following platforms:

  - Linux (Ubuntu)
  - Windows ([Cygwin x64](https://cygwin.com/install.html), [Npcap SDK x64](https://nmap.org/npcap/#download) and [OpenSSL-Windows x64](https://www.openssl.org) are required)

Note: The [OpenSSL](https://www.openssl.org) version >= 1.1.1 is also required.

## How to do it?

They are three different methods:
- Using [Vagrant](https://www.vagrantup.com/)
- Using [Docker](https://www.docker.com/)
- Using [Eclipse TITAN on Windows or Linux](https://projects.eclipse.org/projects/tools.titan/downloads)

How to choose one of these methods is depending of your host system.

NOTE: In all case, if you want to setup an continuous integration process (e.g. Jenkins), Docker is the best choice. 


### The host system is Windows
The both methods require a virtual machine. You can use either VirtualBox or WMware.
In this case, the easiest way is to use Vagrant.


### The host system is Linux
Vagrant requires a virtual machine. You can use either VirtualBox or WMware.
Docker does not need a virtual machine, so it is the more efficant way.

The following clauses describes four ways to build and deploy the CISE  Test System:
- [Using TITAN compiler on a Docker image](#using-titan-compiler-on-a-docker-image)
- [Using development Docker image](#using-development-docker-image)
- [Using Vagrant](#using-vagrant)
- [From scratch](#from-scratch)


## Using TITAN compiler on a Docker image

In this configuration, TITAN compiler is located on a Docker image and the sources and the outputs are located on the host.

Pre-requisites on your host machine:
- Install Docker

Procedure on the host machine:
- Open a Terminal
- Clone the project

```sh
$ git clone --recurse-submodules --remote-submodules https://forge.etsi.org/rep/int/5g-core/nas.git
```

- Select the branch you need:

 devel

```sh
$ git checkout TTF_T048
```

- Execute the installation script to setup the correct environment:

```sh
$ cd ./nas
& ./install.sh
```

- From the NGAP/NAS Conformance Test System root directory, build the Docker image executing the following commands:

```sh
$ cd ./virtualization/docker
$ docker build --no-cache --tag alpine-nas -f Dockerfile --force-rm .
$ docker images
```

To build the NGAP/NAS Test Suite, execute the following command:

```sh
$ ./docker-run.sh build
```

Possble other options are 'clean' to remove all the build outputs or 'rebuild' to force a build of the Test Suite after a 'clean'.

Before to execute the NGAP/NAS Test Suite, prepare, edit and update the configuration file (e.g. AtsNGAP Test Suite):
- Update the following fields:
    - system.NGAP_AMF.params
    - system.N2_gNBaMF_P.params
- Update the PICS and PIXITs accordingly

```sh
$ ln -sf ../../etc/AtsNGAP/AtsNGAP_AMF_open5gs.cfg_ ../../etc/AtsNGAP/AtsNGAP.cfg
$ vi ../../etc/AtsNGAP/AtsNGAP.cfg # To update it
```

To run the NGAP/NAS Test Suite, execute the following command:

```sh
$ ./docker-run.sh run
```

<b>Notes</b>:
- The NGAP/NAS Conformance Test System is listening on port 38412
- Updating the file etc/AtsNGAP.cfg is about:
. Selecting the test(s) to be executed
. Updating value of PICs and PIXITs
. Updating HTTP port setting


## Using development Docker image

In this configuration, the TITAN compiler, the sources and the outputs are located on the Docker image.

Pre-requisites on your host machine:
- Install Docker

Procedure for a Windows host machine:
- On your host machine, open a the Docker Quickstart Terminal and change to a working folder such as ./temp/docker_its

Procedure for a Linux host machine:
- On your host machine, open a terminal and change to a working folder such as $HOME/temp/docker_its

On your host machine, download the following items from NGAP/NAS Conformance Test System project:
- The docker folder
- The .jenkins.sh script file (hidden file) and add the execution rights on it
- Check the rights of the script files and the folders

From the your current directory, execute the following commands:

```sh
$ ./.jenkins.sh
...
```

NOTE The creation and the installations will take some time to achieve
- Start the container

```sh
$ ./virtualization/docker/run-container.sh
...
```

- Switch to the next clause (Usage)


## Using Vagrant

Pre-requisites on your host machine:
- Install [Virtualbox](https://www.virtualbox.org/manual/ch01.html)
- Install [Vagrant](https://www.vagrantup.com/intro/getting-started/)
- Install Vagrant plugin vagrant-vbguest
- Credentials to access [ETSI forge](https://forge.etsi.org/gitlab/users/sign_in)
    - Set the environment variable USERNAME to your ETSI EOL account user name
    - Set the environment variable PASSWORD to your ETSI EOL account password

Procedure:
- On your host machine, open a command line session (PuTTY, DOS window...)
- From the NGAP/NAS Conformance Test System project, clone the Vagrant folder
- In the file Vagrantfile, modify the tag config.vm.provision replacing <username> & <password> strings by your ETSI credentials
- In the Vagrant folder (./virtualization/vagrant), execute the following commands:

```sh
$ vagrant up --provider virtualbox --provision
...
```

NOTE The creation and the installations will take some time to achieve
- Stop vagrant virtual machine

```sh
$ vagrant halt
...
```

- Update the file 'Vagrantfile' to match with your networks configuration
- Re-start the vagrant virtual machine and log to to the machine

```sh
$ vagrant up
...
$ vagrant ssh
```

- Switch to the next clause (Usage)

NOTE The user password is vagrant.


## From scratch

Pre-requisites:
- Install Virtualbox

Procedure:
- Install a new Linux Virtual machine (Mint, Debian...)
- Update your system with the latest version of kernel and security packages
- Install the following packages (According to the Linux chosen, the package naming can be different)
    autoconf
    bison
    build-essential
    cmake
    curl
    dos2unix
    doxygen
    emacs
    expect
    flex
    g++:latest
    gcc:latest
    graphviz
    gdb 
    git-core
    gnutls-bin
    libglib2.0-dev
    libpcap-dev
    libgcrypt-dev
    libncurses5-dev
    libjsoncpp-dev
    libssl-dev
    libtool-bin
    libtool
    libwireshark-dev
    libxml2-dev
    lsof
    ntp
    pkg-config
    qt5-default
    qtmultimedia5-dev
    libqt5svg5-dev
    subversion
    sudo
    sshpass
    tcpdump
    texlive-font-utils
    tshark
    valgrind
    vim
    vsftpd
    xutils-dev 
    tree
    tzdata
    unzip
    wget
    xsltproc

- Clone the NGAP/NAS Conformance Test System project into $HOME/dev folder

```sh
$ git clone --branch=devel --recurse-submodules --remote-submodules https://forge.etsi.org/rep/int/5g-core/nas.git
```

- Execute the script install.sh

```sh
$ ./install.sh
```

- Build a test suite (e.g. AtsNGAP)

```sh
$ export ATS=AtsNGAP && make
```

- Switch to the next clause (Usage)


# Usage

This clause describes how to compile and execute an Abstract Test Suite.
The procedures below illustrate how to run the AtsNGAP test suite. The same procedures will apply for any other NGAP/NAS Test Suite.


Pre-requisites:
- Your machine is installed following one of the installation method describes in the previous clause
- Your are logged as 'etsi' or 'vagrant' user
- Procedure using TITAN command line (only):
    - Open several SSH session (PuTTY...)
    - Change to the directory ~/dev/nas/
    - Modify the file config.mk according to your system:
        - On Linux, comment all the lines using the '#' character
        - On Windows, update the path accordingly
    - Build the test suite AtsNGAP using the following command:

```sh
$ export ATS=AtsNGAP # The Abstract Test Suite you want to build, such as AtsNGAP...
$ make
...
```

Before to execute the NGAP/NAS Test Suite, prepare, edit and update the configuration file (e.g. AtsNGAP Test Suite):
- Update the following fields:
    - system.NGAP_AMF.params
    - system.N2_gNBaMF_P.params
- Update the PICS and PIXITs accordingly

```sh
$ ln -sf ../../etc/AtsNGAP/AtsNGAP_AMF_open5gs.cfg_ ../../etc/AtsNGAP/AtsNGAP.cfg
$ vi ../../etc/AtsNGAP/AtsNGAP.cfg # To update it
```

To run the NGAP/NAS Test Suite, execute the following command:

```sh
$ cd ~/dev/nas/scripts
$ ../run_all.bash
...
```

- The log files are located in ../logs/AtsNGAP folder for this example. You can edit them using any editor or using the Eclipse TITAN log plugins

# Limitations

The following limitations apply:
- AE test suite was not validated;
- CBOR is not supported;
- XML is not supported;
- Subscription/notification mechanism testing not implemented yet.

# How to Report a Bug

The NGAP/NAS Conformance Test System project is under constant development, so it is possible that you will
encounter a bug while using it. Please report bugs at cti_support at etsi dot org.

