Update README file

# NG_NAS

# ETSI 5GNGAP protocol project

## Introduction

## Getting started

This repositories contains the test specificationsfor ETSI 5GNGAP protocols testing, Release 16.

ETSI 5GNGAP protocols project supports:

- ETSI TS 123 501: "5G; System architecture for the 5G System (5GS) (3GPP TS 23.501 version 16.16.0 Release 16)"

- ETSI TS 123 502: "5G; Procedures for the 5G System (5GS) (3GPP TS 23.502 version 16.15.0 Release 16)"

- ETSI TS 124 501: "5G; Non-Access-Stratum (NAS) protocol for 5G System (5GS); Stage 3 (3GPP TS 24.501 version 16.12.0 Release 16)"

- ETSI TS 138 413: "5G; NG-RAN; NG Application Protocol (NGAP) (3GPP TS 38.413 version 16.12.0 Release 16)"

To make it easy for you to get started with GitLab, here's a list of recommended next steps.

Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!

## Contact information

## Add your files

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

- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files

- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:

## 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 were or are currently involved in the evolutions of the ETSI 5GNGAP protocols project:

- TTF T033, 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

```

cd existing_repo

git remote add origin https://forge.etsi.org/rep/int/5g-core/nas.git

git branch -M main

git push -uf origin main

- Select the branch you need:

 devel

```sh

$ git checkout TTF_T048

```

## Integrate with your tools

- Execute the installation script to setup the correct environment:

```sh

$ cd ./nas

& ./install.sh

```

- [ ] [Set up project integrations](https://forge.etsi.org/rep/int/5g-core/nas/-/settings/integrations)

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

## Collaborate with your team

```sh

$ cd ./virtualization/docker

$ docker build --no-cache --tag alpine-nas -f Dockerfile --force-rm .

$ docker images

```

- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)

- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)

- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)

- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)

- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)

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

## Test and Deploy

```sh

$ ./docker-run.sh build

```

Use the built-in continuous integration in GitLab.

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

- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)

- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)

- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)

- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)

- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)

To retrieve the list of the available test cases, execute the following command:

***

```sh

$ ./docker-run.sh list

```

# Editing this README

Before to execute the NGAP/NAS Test Suite, prepare, edit and update the configuration file (e.g. AtsNGAP Test Suite):

When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.

```sh

$ ln -sf ../../etc/AtsNGAP/AtsNGAP_AMF_open5gs.cfg_ ../../etc/AtsNGAP/AtsNGAP.cfg

$ vi ../../etc/AtsNGAP/AtsNGAP.cfg # To update it

```

## Suggestions for a good README

Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.

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

## Name

Choose a self-explaining name for your project.

```sh

$ ./docker-run.sh run

```

## Description

Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.

<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

## Badges

On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.

## Visuals

Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.

## Using development Docker image

## Installation

Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.

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

## Usage

Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.

Pre-requisites on your host machine:

- Install Docker

## Support

Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.

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

## Roadmap

If you have ideas for releases in the future, it is a good idea to list them in the README.

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

## Contributing

State if you are open to contributions and what your requirements are for accepting them.

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

For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

From the your current directory, execute the following commands:

You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.

```sh

$ ./.jenkins.sh

...

```

## Authors and acknowledgment

Show your appreciation to those who have contributed to the project.

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

- Start the container

## License

For open source projects, say how it is licensed.

```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

...

```

- Edit the file ../etc/AtsNGAP.cfg

- Update the following fields:

    - system.mcaPort.params

    - system.mcaPortIn.params

    - system.utPort.params

- To run the test suitem, 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.

## Project status

If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.