# NG112

## Introduction
This repositories contains the test specifications and test adapter code
to test compliance to ETSI TS 103 479 (Emergency Communications (EMTEL); Core elements for network independent access to emergency services).

## Contact information
Email at cti_support at etsi dot org

## License
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

## Standard links
- ETSI TS 103 650-1, Part 1: Test Purposes V1.2.1 - Available [here](https://www.etsi.org/deliver/etsi_ts/103600_103699/10365001/01.02.01_60/ts_10365001v010201p.pdf)
- ETSI TS 103 650-2, Part 2: Test Suite V1.2.1 - Available [here](https://www.etsi.org/deliver/etsi_ts/103600_103699/10365002/01.02.01_60/ts_10365002v010201p.pdf)
- ETSI TS 103 479 V1.2.1, Core elements for network independent access to emergency services - Available [here](https://www.etsi.org/deliver/etsi_ts/103400_103499/103479/01.02.01_60/ts_103479v010201p.pdf)
- ETSI TS 103 698, Emergency Communications (EMTEL); Lightweight Messaging Protocol for Emergency Service Accessibility (LMPE) - Available [here](https://www.etsi.org/deliver/etsi_ts/103600_103699/103698/01.01.01_60/ts_103698v010101p.pdf)
- Next Generation 112 Long Term Definition, accessible [here](https://eena.org/wp-content/uploads/2018/11/Next-Generation-112-Long-Term-Definition-Standard-For-Emergency-Services.pdf)

## RFC links
- RFC 5222 - LoST: A Location-to-Service Translation Protocol, accessible [here](https://tools.ietf.org/html/rfc5222)
- RFC 5985 - HELD, accessible [here](https://tools.ietf.org/html/rfc5985)
- RFC 6155 - Use of Device Identity in HTTP-Enabled Location Delivery (HELD), accessible [here](https://tools.ietf.org/html/rfc6155)
- RFC 3863 - Presence Information Data Format (PIDF), accessible [here](https://tools.ietf.org/html/rfc3863)
- RFC 4119 - A Presence-based GEOPRIV Location Object Format, accessible [here](https://tools.ietf.org/html/rfc4119)
- RFC 5139 - Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO), accessible [here](https://tools.ietf.org/html/rfc5139)
- RFC 7459 - Representation of Uncertainty and Confidence in the Presence Information Data Format Location Object (PIDF-LO), accessible [here](https://tools.ietf.org/html/rfc7459)

NOTE All draft can be found in the 'IETF XML Registry', accessible [here](https://www.iana.org/assignments/xml-registry/xml-registry.xhtml)

# Installation

The ETSI Emergency Communications project builds and tests regularly on the following platforms:

  - Linux (Ubuntu)

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

## How to do it?

They are two different methods:
- Using [Vagrant](https://www.vagrantup.com/)
- Using [Docker](https://www.docker.com/)

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.


## 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 ETSI NG112 Test System
- From the ETSI NG112 Test System root directory, build the Docker image executing the following commands:

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

To build the NG112 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'.

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

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

Before to execute the NG112 Test Suite, prepare, edit and update the configuration file:

```sh
$ ln -sf ../../etc/AtsXxx/AtsXxx_yyy.cf_ ../../etc/AtsXxx/AtsXxx.cfg
$ vi ../../etc/AtsXxx/AtsXxx.cfg # To update it
```

To execute the NG112 Test Suite, execute the following command:

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

<b>Notes</b>:
- The NG112 Test System is listening on port 443
- Updating the file etc/AtsXxx/AtsXxx.cfg is about (e.g. etc/AtsBCF/AtsBCF.cfg):
. 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
- On your host machine, clone the ETSI EEmergency Communications project. NOTE that only Docker folder and .jenkins.sh script file are required
- From the ETSI Emergency Communications project root directory, execute the following commands:

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

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

```sh
$ ./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 ETSI Emergency Communications 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, 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
    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
- In your home directory, create the following folders: 
    - $HOME/frameworks, 
    - $HOME/dev
    - $HOME/lib

- In $HOME/frameworks, build the following package:
    - Eclipse IDE for C/C++ Developers, according the procedure specified [here](https://www.eclipse.org/cdt/)
    - TITAN, according the procedure specified [here](https://github.com/eclipse/titan.core)
    - Import the TITAN plugin into your Eclipse IDE, according the procedure specified [here](https://github.com/eclipse/titan.core)

- Install LibOSIP framework
```sh
$ cd ${HOME}/frameworks
$ git clone https://git.savannah.gnu.org/git/osip.git ./osip
$ cd osip
$ ./autogen.sh
$ ./configure --prefix=/home/etsi
$ make && make install
```

- Clone the ETSI Emergency Communications project into $HOME/dev folder

```sh
$ git clone --recurse-submodules --branch devel https://forge.etsi.org/rep/emtel/NG112.git ./NG112
$ cd /home/etsi/dev/NG112/titan-test-system-framework
$ git checkout devel
$ cd /home/etsi/dev/NG112/titan-test-system-framework/ttcn/LibHttp
$ ln -sf module_emtel.mk module.mk
```

- Apply patches
```sh
$ cd /home/etsi/dev/NG112
$ cp ./ttcn/patch_lib_common_titan/module.mk ./ttcn/LibCommon/
$ cp ./ttcn/patch_lib_common_titan/*.ttcn ./ttcn/LibCommon/
$ cp ./ttcn/patch_ims_titan/*.ttcn ./ttcn/LibIms/ttcn/
$ cp ./ttcn/patch_ims_titan/module.mk ./ttcn/LibIms/
$ cp ./ttcn/patch_sip_titan/*.ttcn ./ttcn/LibSip/ttcn/
$ cp ./ttcn/patch_sip_titan/module.mk ./ttcn/LibSip/
```

- Update your default environment with the content of the script $HOME/dev/NG112/scripts/devenv.bash.ubuntu

- Switch to the next clause (Usage)


# Generate certificates for TLS and NG112 security support 

This clause describes how generate certificates desrived from Let's encrypt certificate. These certificate will be used for TS mutual authentication.
<b>NOTE:</b>
- Certficates shall be renewed every 3 months
- The port 80 shall be vailable for standalone validation

Pre-requisites:
- You need to install python and [certbot](https://manpages.ubuntu.com/manpages/impish/en/man1/certbot.1.html).

To generate certifcates, execute the following command:

```sh
$ export REQUESTS_CA_BUNDLE=$(dirname `python -c "import certifi; print(certifi.where())"`)
$ mkdir -p $HOME/var/ssl
$ sudo certbot certonly --debug --ng112-tls-cert --config-dir $HOME/var/ssl --work-dir $HOME/var/ssl  --logs-dir $HOME/var/ssl --standalone --agree-tos --email <your email> -d <your domain> -w $HOME/var/ssl/
```

<b>NOTE:</b> For testing certificate generation and renewal, use the certbot's --dry-run option.


# Usage

This clause describes how to compile and execute an Abstract Test Suite.
The procedures below illustrate how to run the CAM test suite. The same procedures will apply for any other ETSI Emergency Communications 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 Eclipse TITAN:
- Start eclipse using a new workspace, (e.g. with the name workspace_titan)
- Download and follow the steps to install Eclipse plugins for TITAN, accessible [here]{https://www.eclipse.org/downloads/download.php?file=/titan/Eclipse_installationguide.pdf}
- Open the workspace_titan
- Create a new TITAN project (e.g. NG112)
- Import the .tpd file located at the root level of the project

Procedure in TITAN command line:
- Open several SSH session (PuTTY...)
- Change to the directory ~/dev/NG112/
- Build the test suite you want to exectue (e.g. LIS test suite)

```sh
$ cd ~/dev/NG112/
$ export ATS=AtsLIS
$ make
...
```

- Edit the file ../etc/AtsLIS/AtsLIS.cfg
- Update the following fields:
    - system.httpPort.params
    - Caller.SIPP.params
    - Ecrf.SIPP.params
    - CallTalker.SIPP.params

- To run the test suitem, execute the following command:

```sh
$ cd ~/dev/NG112/scripts
$ ./run-all.bash
...
```

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


# How to Report a Bug

The ETSI Emergency Communications 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.
