# Install SlapOS Node (COMP-123) LTE-Box

This document explains how to use the NMS Network Management System to install and configure the Amarisoft Stack on a Standard PC (or Server) containing a SDR Radio board in order to provide 4G/5G networks services. This tutorial can be applied to any deployment of Amarisoft stack running on a Linux Distrubution.

For the purpose the tutorial, this standard computer is called LTE-Box(COMP-123), and it is considered in SlapOS network, as a normal computer/server .

To follow the steps outlined in this section, you need to have:

- access to a SlapOS Master (COMP-ROOT) - installing and accessing a SlapOS Master
- a slave node (COMP-0) providing necessary software services - see installing a SlapOS node (COMP-0)
- a new Debian server to register as LTE-Box

# Table of Content

- LTE Box Introduction
- LTE Box Installation
- Add Amarisoft LTE to Software Catalogue
- Supply LTE Software on LTE Box
- Scenario 1: Instantiating LTE - Default
- Scenario 2: Instantiating LTE - EPC/ENB
- Add Simcard to SimcardDB

# LTE Box Introduction

This section will introduce the LTE Box and how to request a default eNodeB deployment. It will show the different types of deployment covered in this tutorial as well as rationale for doing so.

# Requesting Default eNodeB Deployment

- Lab Version
- Production Version

This tutorial will teach how to setup an eNodeB/ePC server with the Amarisoft stack in two different ways.

## Lab Version

The `software-type` Default will provide a "Lab" version in which the following four services of the Amarisoft stack are deployed on the same computer in a cluster mode (Scenario 1):

- 1 instance of LTE eNB
- 1 instance of LTE ePC (MME)
- 1 instance of LTE IMS
- 1 instance of LTE MBMS

## Production Version

For production we recommend to deploy using individual instances, which will allow to create boxes with multiple LTE eNB instances. This tutorial shows how to deploy the following as separate instances (Scenario 2):

- 1 instance of LTE ePC (MME)
- 1 instance of LTE eNB

This tutorial doesn't cover the deploment of standalone IMS and MBMS as they are complementary services. However, the user can deploy them in a similar way as LTE EPC.

# Amarisoft LTE Software Release

The Amarisoft LTE Software Release automates the deployment of Amarisoft Binaries in an orchestrated way. The Software Release contains all components (lteenb, ltemme, lteims and ltembms) provided by amarisoft stack:

- lteenb - eNodeB software is the server accepting connection from UI (user interfaces)
- ltemme - Mobile Management Entity - the core network which handles orchestration of eNodeBs in case UI switches from one to another
- lteims - IP Multimedia System is another protocol such as LTE but designed for services over IP. Please read http://www.differencebetween.com/difference-between-lte-and-vs-ims-2/
- ltembmsgw - Multimedia Broadcast Multicast Services (Gateway) is technology which broadcast the same multimedia content into multiple IP addresses at once to save bandwidth.

Those binaries are started in the foreground, originally on screen. However, it is undesireable to have binaries inside one screen because then it is not easy to control and monitor their resource usage. Thus NMS is using four on-watch services (which will take action if one process is down.)

The configuration file of the Amarisoft Stack is present here:

    $MASTER_URL/raw/master/slapos/software/lte/software.cfg

# Glossary

- MME
- IMS
- MBMSGW

Terms necessary to understand:

- MME (ePC)
  Is the core network. This binary keep track of UEs and to which eNodeB they are currently connected. It reroutes traffic when UE switches between eNodeBs. MME also serves as a service bus thus all services must register within MME.
- IMS
  Service connected into MME bus. IMS handles circuit-ish services over IP whereas LTE would have failed because it is intended as data-over-IP service. I think that VoLTE is actually using IMS.
- MBMSGW
  MBMS Gateway is a standalone component connected to BMSC (Broadcast Multicast Service Centre), server supporting streaming content from providers, which is another component inside our core network not provided by Amarisoft. MBMS Gateway is connected to MME which then manages MBMS sessions. I think that MBMS itself handles data delivery by posting the data onto MME bus.

# License

    sudo su
    # mkdir /etc/amarisoft

    # # Check if you have the licenses
    # ls ~/.amarisoft/lte*

    # # Copy Licenses into /etc/amarisoft
    # cp ~/.amarisoft/* /etc/amarisoft

    # chmod ugo+rx /etc/amarisoft
    # chmod -R ugo+r /etc/amarisoft

The Amarisoft Stack requires licenses to work. YOU HAVE TO ENSURE YOU HAVE THE APPROPRIATE LICENSE TO RUN THE AMARISOFT STACK ON YOUR SERVER. In case of doubt, please contact Amarisoft directly for the licenses.

Once you have the license, please place them on the following folder for the purpose of the tutorial:

    /etc/amarisoft/

.

Also ensure, users can access it:

    # chmod ugo+rx /etc/amarisoft
    # chmod -R ugo+r /etc/amarisoft

After this you can proceed with the installation of your Node.

# LTE Box Installation

The following steps are partially covered in a generic way in installing SlapOS node (COMP-0). The main difference is for all LTE-Box servers, the services provided by COMP-0 (Frontend, IPv6, Registry, SimcardDB) are already available - so setup is somewhat easier.

# SlapOS Master Dashboard

Start by logging into your SlapOS Master Dashboard with a user with administrative privileges to request a new server token. Click the Services menu on the side menu to open the list of existing services.

# List of Instantiated Services

Head to the list of services by clicking on the Services button on the side menu. The list will show all services currently instantiated (not the software currently installed!). To create an instance of an installed software, click the Add button in the subheader.

# Create New Res6st Token Instance

The list of available services is the same as the list of installable software releases used earlier when installing the service. Select Re6st as this is the service we want to provide. The differentiation between Registry and Token will be made via the configuration parameter Software-Type.

# Select Re6st Service Version

As during installation, please choose the latest version.

# Re6st Registry Configuration

Select Software Type `Re6st Token` which will load a form with instance-specific parameters. As mentioned, the token is actually a slave instance of the Registry (and in case of COMP-0 a first gateway node).

Every new node will require a token, so give this token a recognizable name (`Re6st-LTE-Box-123` for example).

Select the Computer on which the Registry of your SlapOS Master was installed at the bottom of the page, then click Proceed to instantiate the service and be forwarded to the list of current services. Refresh the page, it may take a few minute for the node to be instantiated and the token to appear. It is a single use token to connect one other node to the network.

# Instantiate Re6st Token

Click Proceed to instantiate a new token. Refresh the list of instantiated services to make the token appear. Click on it to access the connection parameters.

# Token Connection Parameters

Locate the token in the Connection Parameters. It might require a few minutes to show up. Refresh the page to see whether the token has been instantiated.

You can now install Re6st on this machine.

# Installing Re6st

    sudo su
    # yum install wget

    (...)

    # wget https://deploy.erp5.net/re6st && bash re6st

ssh into the terminal of your server, switch to root and verfiy wget is available. Then install re6st as shown above. At some point the script will ask you:

    What is the Url of the Re6st registry [https://re6stnet.nexedi.com]:
    Please insert your re6stnet token [notoken]:

Provide the master-url you noted when setting the port forwarding for the Re6st Registry in installing the SlapOS Master (it should be `http://[your_IPv4_address]:9201`) along with the token created in the previous steps and continue. The setup should finish without errors:

    ...
    PLAY RECAP *********************************************************************
    127.0.0.1                  : ok=24   changed=7   unreachable=0   failed=0

# Verify Files Created

    sudo su
    # ls /etc/re6stnet/
    ca.crt     cert.cert     cert.key     re6stnet.conf     README

Verify that the configuration files were created.

# Verify Re6st is Running

    sudo su
    # service re6stnet status

You can use the above command to see whether Re6st is working. The output should be similar to:

    ● re6stnet.service - (null)
       Loaded: loaded (/etc/init.d/re6stnet)
       Active: active (running) since Fri 2018-03-09 16:43:23 UTC; 6min ago
       Process: 26395 ExecStop=/etc/init.d/re6stnet stop (code=exited, status=0/SUCCESS)
       Process: 26423 ExecStart=/etc/init.d/re6stnet start (code=exited, status=0/SUCCESS)
       CGroup: /system.slice/re6stnet.service
               ├─26431 /opt/re6st/parts/python2.7/bin/python2.7 /usr/sbin/re6stnet
    @re6stnet.conf
               ├─26437 openvpn --dev-type tap --dev re6stnet-tcp --persist-tun --p
    ersist-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/r
    e6st/ovpn-client --tls-server --mode server --clien...
               ├─26444 babeld -h 15 -H 15 -L /var/log/re6stnet/babeld.log -S /var
    /lib/re6stnet/babeld.state -I /var/run/re6stnet/babeld.pid -s -C ipv6-subtree
    s true -C default max-rtt-penalty 5000 rtt-max 500 rt...
               ├─26537 openvpn --dev-type tap --dev re6stnet1 --persist-tun --per
    sist-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/re
    6st/ovpn-client --nobind --client --remote 163.172.45...
               └─26862 openvpn --dev-type tap --dev re6stnet2 --persist-tun --per
    sist-key --script-security 2 --up /opt/re6st/eggs/re6stnet-0.485-py2.7.egg/re
    6st/ovpn-client --nobind --client --remote 52.36.124....

      Mar 09 16:43:23 slapostest2 systemd[1]: Started (null).

After this step Re6st is installed and the machine is accessable over IPv6.

# Get SlapOS Master Token

Head to the SlapOS Dashboard at:

    https://master.YOUR_DOMAIN/ (preferred the url)

Otherwise:

    https://[instance-IPv4]/erp5/web_site_module/hostingjs/

and log in as a regular user (the zope username/password will not work, you should have created a user account on the SlapOS Dashboard while setting up the SlapOS Master). Click on the Servers link in the side to go to your list of servers.

When using the single line installer, you have to provide a X509 security token to identifiy your node with a SlapOS Master and enable it to manage the node within a network. To get such a token, in the subheader, click Token.

# Association Token

Click Proceed to request a token. Once it's generated, copy the token for later. Note, that the token can only be used once. If the installation of SlapOS fails for whatever reason and you need to retry, you need to request a new token before. Head back to the terminal.

# Single Line Installer

    sudo su
    # wget deploy.erp5.net/slapos && bash slapos

    ...

    What is the url to the SlapOS Master API? [https://slap.vifib.com/]:
    What is the url to the SlapOS Master Website? [https://slapos.vifib.com/]:
    What is this computer name? [noname]:
    If you have slapos token if you have? [notoken]:

Continue and use the single line installer. You will be asked a set of questions during the installation. As you are connecting to your own master, on the first question, please point to port 5443 of your master's IPv4 adress, so enter `https://[your_IPv4_address]:5443` and on the second question, please add your SlapOS Master dashboard url. Same as you are using to get the token:

    https://master.YOUR_DOMAIN
    OR
    https://[your_IPv4_address]:443/erp5/web_site_module/hostingjs/ (If you used this one)

Choose a name for your computer (like LTE-BOX-1 to identity it in your network and finally enter the association token you have received earlier from your SlapOS Master. The installation can be repeated in case something goes wrong or you would like to change some of the entered parameters.

Once the installation has finished without errors, you should see:

    ...
    PLAY RECAP *********************************************************************
    127.0.0.1                  : ok=12   changed=4   unreachable=0   failed=0

In case installation fails and you want to start over, you need to request a new token as mentioned above and, depending on whether already created, remove any existing configuration in `/etc/opt/slapos/slapos.cfg` before restarting.

You can verify that SlapOS was installed by trying:

    # slapos node
    watchdog                   RUNNING   pid 13270, uptime 0:00:03

And (re)formatting the SlapOS node:

    # slapos node format --now
    2018-04-21 13:07:29 slapos[13279] INFO Updating Computer
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart0
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart1
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart2
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart3
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart4
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart5
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart6
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart7
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart8
    2018-04-21 13:07:30 slapos.format[13279] INFO Partition resources saved to slappart9
    2018-04-21 13:07:30 slapos[13279] INFO Posting information to 'https://54.37.31.108:5443/'
    2018-04-21 13:07:30 slapos[13279] INFO slapos successfully prepared the computer.

# SlapOS Dashboard - Registered Servers

Head back to your SlapOS Dashboard and verify the list of servers now includes your SlapOS Node which was associated to your network using the token you had created. You may have to refresh the page for the server to show up.

Note, the entry has three clickable areas:

- The line itself (click server name for example) points to the server configuration
- Clicking the Computer button will open the monitor - the green color indicates the server is active and contacting the Master.
- As this server does not have any computer partitions installed yet, the second button next to Computer is still missing.

# Add Amarisoft LTE to Software Catalogue

As Amarisoft LTE is NOT a standard software included in SlapOS, the software release has to be manually added to the software catalog before being able to supply and instantiate it. Note, this has to be done only once. However the steps are the same for adding and also updating(!) all software releases on SlapOS.

The following steps require a user with administator privileges which should have been created during installation of the SlapOS Master for adding SimcardDB to the catalog.

# Administrator Login to ERP5 Interface

Login to the ERP5 interface underlying the SlapOS Dashboard with the user with administrator privileges. The ERP5 interface can be accessed at `[your_IPv4_address]/erp5/`.

Warning: Don't login as "zope" user !

# Access Software Product Module

Once logged in click on Software Products or select Software Product Module from the Modules select field.

# Add Software Product

On the software product page, select Action and Add Software Product.

# Define Software Product

Set Title and Reference, then save by clicking the disk icon.

# Publish Software Product

The final step is to publish the Software Product. Select Action and Publish to change the workflow change.

# Published Software Product

Confirm and once you are back on the Software Product page and the state is changed to Published, click on the ERP5 breadcrumb to get back to the main homescreen.

# Access Software Release Module

Next click on Software Releases or select Software Release Module from the Modules select field.

# Add Software Release

Repeat the steps, so once on the software release page, select Action and Add Software Release.

Note, that whenever you want to upgrade a software release, you have to create a new software release entry with the difference being the version and `software.cfg` being pointed to, which can both be set in the next steps.

# Locate Software.Cfg Url

Head over to the repository you are using to host software releases and locate the `software.cfg` file which contains the instructions for building your your software. Find the URL of this software release. Note, that you can use different releases, for example:

- latest development:

      https://lab.node.vifib.com/nexedi/amarisoft/raw/master/slapos/software/lte/software.cfg

- latest tagged version:

      https://lab.node.vifib.com/nexedi/amarisoft/raw/[TAG]/slapos/software/lte/software.cfg

`[TAG]` can be any value listed on the published releases, found on https://lab.node.vifib.com/nexedi/amarisoft/tags. Continue using the latest tagged version which is v0.2. Note down the following url:

    https://lab.node.vifib.com/nexedi/amarisoft/raw/v0.2/slapos/software/lte/software.cfg

# Define Software Release

Fill the form as shown in the screenshot. Make sure you select HTTP and provide the url to your `software.cfg`. Also select the software product for which this release is made, define a version and once all fields have been filled out, click the disk icon to save.

# Publish Software Release Alive

The final step is to publish the Software Release Alive (publishing alive, will allow to edit the provided data in case necessary). Select Action and Publish Alive to change the workflow change.

# Published Software Release

Confirm and once you are back on the Software Release page and the state is changed to Published Alive, click on the ERP5 breadcrumb to get back to the main homescreen.

# Software Available in SlapOS Dashboard

Head over to the SlapOS Dashboard. If you pick a computer and click Supply, the newly defined software will now be on the list. We can continue and install LTE on this machine.

# Supply LTE Software on LTE Box

This section will cover the steps for installing LTE on the newly formatted server using the SlapOS Dashboard.

# Supply LTE Software on Box

Back in the SlapOS Dashboard go to Servers and select the LTE Box you have created. There is no software currently installed. Click Supply in the subheader.

# Select LTE Software Release

Select the LTE software release.

# Select LTE Software Release Version

Select the latest version.

# Launch LTE Software Release Installation

Click Proceed in the header to start installation.

# Wait for LTE Installation

After clicking Proceed you will be forwarded to the installation status page.

Installation will take some time depending on the software you are installing, so either refresh the current page or check installation status directly by either going to your Servers list and selecting the machine you chose during installation or clicking directly on Computer Reference.

# Verify LTE Installation

You can see the installed service is now available in the bottom list. The indicator will stay red until the software has finished compiling and installing. Once the installation status bar changes to green on a refresh of the page, the installation has finished.

You can follow the compilation by looking at the `slapos-node-software.log` using:

    # tail opt/slapos/log/slapos-node-software.log -f

in your terminal.

# Scenario 1: Instantiating LTE - Default

The following steps cover setting up the "Lab" Version on the LTE Box with all relevant services instantiated together.

# List of Instantiated Services

Head to the list of services by clicking on the Services button on the side menu. The list will show all services currently instantiated (not the software currently installed!). To create an instance of an installed software, click the Add button in the subheader.

# Select LTE Service

The list of available services is the same as the list of installable software releases used earlier when installing the service. Select LTE as this is the service we want to provide.

# Select LTE Service Version

As during installation, please choose the latest version.

Note, that this is an easy case, as there is only a single version installed on one node. More complex networks will likely have multiple versions of a software installed on different nodes.

# LTE Lab Service Configuration

You will reach the service configuration menu. Give your service a recognizable name (LTE_ALL_IN_ONE in the example), select `Software-Type` Default (denoting LTE Lab), pick the Computer/Box to install the LTE Lab at the end of the form and then fill out the form parameters. If required, you can expand the form to add additional parameters. Parameters include:

- Log Options: Log options settings for enb.cfg, mme.cfg, ims.cfg and mbms.cfg (See Amarisoft official documentation for understand the format)
- GTP bind address: IP address of the network interface connected to the core network
- MME address: Address of MME for S1AP connection
- UE configuration path (optional): A path containing the ue_db configuration on the machine. Usefull for simple Tests
- RF Parameters / Tx_gain: Tx gain (in dB)
- RF Parameters / Rx gain: Rx gain (in dB)
- License Key Path: Path to where the license *.key files are on the filesytem (to be used instead ~/.license or ~/.amarisoft folder
- Cell List: Contains one or more cells configuration to be set on enb.cfg configuration
- Cell List / DL EARFCN: Downlink EARFCN of the cell
- Cell List / Physical cell ID: Physical cell ID

Click Proceed to begin instantiation.

This list of parameters are only a subset of the full amarisoft parameters, you can learn how to extend this list on the "Lecture 6".

# LTE Lab Service Instantiation

Refresh the list of current services to show the new service and status.

You can follow the compilation progress by looking at the `slapos-node-software.log` using:

    # tail opt/slapos/log/slapos-node-software.log -f

The LTE Lab will be installed inside a computer partition (see SlapOS system requirements)

# Monitor Service Connection Parameter

If you click on the instantiated service, you can see the connection parameters. By default they are not expanded.

# Expand Service Connection Parameters

By clicking on the Parameter Entry buttons, you can expand the drawers to show all subsequent parameters.

# Service LTE Lab Process List

Scroll down on the connection parameter page. Once the service has been fully instantiated you can see all running processes at the bottom of the page in the table Instances.

# Scenario 2: Instantiating LTE - EPC/ENB

The following steps cover setting the EPC/MME and ENB separately.

# List of Instantiated Services

Head to the list of services by clicking on the Services button on the side menu. The list will show all services currently instantiated (not the software currently installed!). To create an instance of an installed software, click the Add button in the subheader.

# Select LTE Service

The list of available services is the same as the list of installable software releases used earlier when installing the service. Select LTE as this is the service we want to provide (the differentiation will only be made during configuration).

# Select LTE Service Version

As during installation, please choose the latest version.

Note, that this is an easy case, as there is only a single version installed on one node. More complex networks will likely have multiple versions of a software installed on different nodes.

# LTE EPC Service Configuration

You will reach the service configuration menu. Give your service a recognizable name (EPC-STANDALONE in the example), select `Software-Type` EPC pick the Computer/Box to install the LTE EPC at the end of the form and then fill out the form parameters.

Click Proceed to begin instantiation.

# LTE EPC Service Instantiation

Refresh the list of current services to show the new service and status.

You can follow the compilation progress by looking at the `slapos-node-software.log` using:

    # tail opt/slapos/log/slapos-node-software.log -f

# Monitor Service Connection Parameter

If you click on the instantiated service, you can see the connection parameters.

# Verify Service Instantiated

Once the monitoring status turns green on a page refresh, the EPC has been instantiated successfully. Then we can add the ENB. Click the Add button in the subheader.

# Select LTE Service

The list of available services is the same as the list of installable software releases used earlier when installing the service. Select LTE as this is the service we want to provide (the differentiation will only be made during configuration).

# Select LTE Service Version

As during installation, please choose the latest version.

Note, that this is an easy case, as there is only a single version installed on one node. More complex networks will likely have multiple versions of a software installed on different nodes.

# LTE ENB Service Configuration

You will reach the service configuration menu. Give your service a recognizable name (eNB-STANDALONE in the example), select `Software-Type` eNB pick the Computer/Box to install the LTE eNB at the end of the form and then fill out the form parameters. Note, that if you have multiple boxes on your network, you can (supply and) instantiate eNB on any of the available boxes.

Click Proceed to begin instantiation.

# LTE EPC Service Instantiation

Refresh the list of current services to show the new service and status.

You can follow the compilation progress by looking at the `slapos-node-software.log` using:

    # tail opt/slapos/log/slapos-node-software.log -f

# Monitor Service Connection Parameter

If you click on the instantiated service, you can see the connection parameters.

# Verify Service Instantiated

Once the monitoring status turns green on a page refresh, the eNB has been instantiated successfully.

# Add Simcard to SimcardDB

Once the EPC and eNB have been setup, the system should be ready to operate. The eNB will query the SimcardDB in regular intervals for new simcard ids. In this section we will add a simcard to the SimcardDB. You could then investigate when the simcard id becomes available on the eNB and whether it can be used (both steps are not part of the tutorial).

# List of Instantiated Services

Head to the list of services by clicking on the Services button on the side menu.

# Create New SimcardDB Instance

Select SimcardDB as this is the service we want to provide. The differentiation between SimcardDB and Simcard will be made on the configuration parameter Software-Type

# Select SimcardDB Service Version

As during installation, please choose the latest version.

# SimcardDB Configuration

Select `Software Type` SimCard, choose the computer which supplied the SimcardDB and fill out the configuration parameters as shown.

Click proceed to instantiate the new SimCard. This is the end of the tutorial for setting up an LTE Box.

# Thank You

- Nexedi SA
- 147 Rue du Ballon
- 59110 La Madeleine
- France

- nexedi.com/contact