C3PO Core applications build, installation, provisioning and run guide.

About this README

This README contains the instructions to build, install, and configure the 
core C3PO modules and all dependent external projects, and the Cassandra 
database, for use.

Supported Operating System: Ubuntu 16.04 (only) 

*** You can skip straight to the INSTALLATION section to get started. Basic
C3PO information is given below.

C3PO is composed of 2 sets of modules:

1. C3PO Modules:

    A] Core C3PO Modules

        Cassandra DB
        HSS - Home Subscriber Server, supports interaction with the MME via the
              S6a interface and with the SCEF via the S6t interface
        MME - Mobile Management Entity
        UTIL - C3PO Utility Library used by all C3PO applications

    B] Optional C3PO Modules
  
        CDF - Charging Data Function, currently a stub that implements a 
              minimal Rf interface
        CTF - Charging Trigger Function, receives billing records from the data
              plan via a CSV file and forwards the data to the CDF via the Rf
              interface
        HSSGTW - Home Subscriber Server Provisioning Gateway, provides a 
              REST-ful interface for provisioning UE's in the HSS's database
        HSSSEC - Home Subscriber Server Security Library, a standalone 
              library that implements the security algorithms utilized by the 
              HSS
        PCRF - Policy and Charging Rules Function, provides the basic 
              functionality to interact with the PCEF, TDF and TSSF

    A minimal, functional, C3PO installation can be achieved by installing only
    the core C3PO modules.

2. External Modules

    All C3PO applications such as the HSS or the MME, require the external 
    modules listed below. An installation script is provided to automate the 
    fetch, build, and installation of each of these components. The external 
    modules are:

    freeDiameter (https://gerrit.opencord.org/#/admin/projects/freeDiameter)
        Diameter protocol implementation, forked from 
    http://www.freediameter.net
    c-ares (https://github.com/c-ares/c-ares.git)
        asynchronous DNS resolver library
    cpp-driver (https://github.com/datastax/cpp-driver.git)
        DataStax C/C++ Driver for Apache Cassandra
    RapidJSON (https://github.com/miloyip/rapidjson.git)
        A fast JSON parser/generator for C++ with both SAX/DOM style API
    spdlog (https://github.com/gabime/spdlog.git)
        Very fast, header only, C++ logging library
    Pistache (https://github.com/oktal/pistache.git)
        Pistache is a modern and elegant HTTP and REST framework for C++

Conventions followed in the document:
1. Text enclosed in <> such as <Cassandra_Server_IP> requires input specific
to your setup, such as an IP address
2. Text enclosed in {} such as {installation_dir} requires a value of your 
choice

============
INSTALLATION 
============

For C3PO deployment with NG40 and NGIC please refer network diagram at:
https://wiki.opencord.org/download/attachments/2556285/INTEL_NG40_Installation_HIO_RACKE3_RAN10_MME_ILEPC3.xlsx?api=v2

A] Installation of C3PO Core Modules

Install each core C3PO module on a separate server/VM.

1. Go to Cassandra server server/VM.

2. Install Cassandra

    (a) On the Cassandra database server, clone the c3po repository into your
        {installation_root} directory.

        #cd {installation_root}
        #git clone https://gerrit.opencord.org/c3po

    (b) Install Java 8 and Cassandra on the Cassandra server

        #sudo add-apt-repository ppa:webupd8team/java
        #sudo apt-get update
        #sudo apt-get install oracle-java8-installer
        #echo "deb http://www.apache.org/dist/cassandra/debian 21x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
        #curl https://www.apache.org/dist/cassandra/KEYS | sudo apt-key add -
        #sudo apt-get update
        #sudo apt-get install cassandra

    (c) Verify that Cassandra is installed and running

        #nodetool status

        The output should look something like:
 
        Datacenter: DC1
        ===============
        Status=Up/Down
        |/ State=Normal/Leaving/Joining/Moving
        --  Address         Load       Tokens  Owns   Host ID                               Rack
        UN  127.0.0.1       438.46 KB  256     100.0% a7e9c21e-79b9-4928-a524-1a0ae5164c49  RAC1 

3. Go to Individual servers Install External Modules and C3PO Applications such as HSS, MME

  For all servers or VM's that will run any C3PO applications, perform the
  following steps.

    (a) Clone the c3po repository into your {installation_root} directory.

         #cd {installation_root}
         #git clone https://gerrit.opencord.org/c3po

    (b) Build and install all components by running install.sh and performing
        each step (invoking each option in the menu in sequence).
    
         #./install.sh

    This will install all the required external modules and the core C3PO 
    modules.

=============
CONFIGURATION
=============

A] Configure Cassandra
 
    The Cassandra server does not need any of the C3PO applications, however 
    there are some C3PO scripts and files that are required to configure the 
    database after Cassandra is installed.  

    The minimal Cassandra configuration required to bring up a running C3PO
    is given below:

    (a) Go to Cassandra server/VM
    
    (b) Stop Cassandra and cleanup the log files before modifying the 
        configuration

        #sudo service cassandra stop
        #sudo rm -rf /var/lib/cassandra/data/system/*
        #sudo rm -rf /var/lib/cassandra/commitlog/*
        #sudo rm -rf /var/lib/cassandra/data/system_traces/*
        #sudo rm -rf /var/lib/cassandra/saved_caches/*

    (c) Update the Cassandra configuration

        Update /etc/cassandra/cassandra.yaml as indicated below.  
        The <Cassandra_Server_IP> address should be the IP address of 
        the Cassandra server that the HSS will use to connect to Cassandra. The
        "..." below indicate configuration lines between values that need to be
        modified.

        ...
        cluster_name: "HSS Cluster"
        ...
        seed_provider:
            - class_name: org.apache.cassandra.locator.SimpleSeedProvider
            - seeds: "<Cassandra_Server_IP>"
        ...
        listen_address: <Cassandra_Server_IP>
        ...
        rpc_address: <Cassandra_Server_IP>
        ...
        endpoint_snitch: GossipingPropertyFileSnitch

    (d) Update /etc/cassandra/cassandra-rackdc.properties as indicated below.

        prefer_local=true

    (e) Start Cassandra with the new Configuration

        #sudo service cassandra start

    (f) Verify that Cassandra is running with the updated configuration

        #nodetool status

        The output should look something like:
 
            Datacenter: DC1
            ===============
            Status=Up/Down
            |/ State=Normal/Leaving/Joining/Moving
            --  Address         Load       Tokens  Owns   Host ID                               Rack
            UN  192.168.112.60  438.46 KB  256     100.0% a7e9c21e-79b9-4928-a524-1a0ae5164c49  RAC1

    (g) Create the HSS Database Schema in Cassandra

        #cd {installation_root}
        #cqlsh --file hss/db/oai_db.cql <Cassandra_Server_IP>
    
    For example:  cqlsh --file hss/db/oai_db.cql 192.168.112.60
    For more information refer to {installation_root}/db_docs/Cassandra_Single_Node_Install.docx

B] Configure the C3PO Core

    (a) HSS
        1. Go to HSS server/VM
        
        2. Update the Diameter Configuration File
            In {installation_root}/hss/conf/hss.conf update the following 
            values accordingly:

                Identity - The diameter identity. The default value is 
                           hss.openair4G.eur
                Realm - The diameter realm (everything past the first period 
                        of the Identity).  The default value is openair4G.eur
          
        3. Create Diameter Certificates

        NOTE: The "Diameter Identity" is a fully qualified domain name that is
        used to access the the Diameter peer.  The "Diameter Host" is 
        everything up to the first period of the "Diameter Identity". The 
        "Diameter Realm" is everything after the first period of the 
        "Diameter Identity".  

            Using the "Identity" configured in 
            {installation_root}/hss/conf/hss.conf, execute the following 
            commands.

                #cd {installation_root}/hss/conf
                #../bin/make_certs.sh <diameter_host> <diameter_realm>
    
            For Example: ../bin/make_certs.sh hss openair4G.eur
    
        4. Update the HSS Configuration File

            In {installation_root}/hss/conf/hss.json update the following 
            values accordingly. Assuming no name changes in the other 
            configuration files, the only value that needs to be updated is 
            "casssrv".

                fdcfg - The name of the Diameter configuration file, the 
                        default is conf/hss.conf
                originhost - Same as the Identity set in hss.conf.
                originrealm - Same as the Realm set in hss.conf.
                gtwhost - The IP address(es) the HSS REST interface will 
                          listen to process HSS gateway commands. The default 
                          is "*".
                gtwport - The port the HSS REST interface will listen to 
                          process HSS gateway commands.
                casssrv - The IP address of the Cassandra database server,
                          <Cassandra_Server_IP> that the HSS will connect to. 
                          ***UPDATE "casssrv" ***
                cassusr - The Cassandra user name.  The default value is 
                          "root".
                casspwd - The Cassandra password.  The default value is "root".
                cassdb - The Cassandra keyspace for the HSS data. The default 
                         value is "vhss".
                randv - The default value is true.
                optkey - The operator key. The default value is
                         "63bfa50ee6523365ff14c1f45f88737d" (which should 
                         match the NG40 default key).
                reloadkey - If true, the OPc values for all IMSI's will be re-
                            calculated when the HSS is started.

C] Configure NG40 tool(not part of C3PO) for testing
    Configure NG40 setup to connect with C3PO MME and SGW-data plane as follows.
    Update '{ng40_root_dir}/network.def.ilepc' in NG40 to configure for following:
		
    $S1_DEV : List (comma separated in []) of Linux ethernet device name per 
            RAN used for eNB S1MME interface 
    $S1_IP_NET : IP address / subnet bits of the first eNB S1MME interface. 
            IPs are incremented by 1 for each eNB.
            $S1U_IP : IP address of the first eNB S1U interface.  IPs are 
                     incremented by 1 for each eNB.
            $MME_IP : S11 IP address of MME server.
    $AS_IP : List (comma separated in []) of AppServer start IP per RAN.
    $AS_IPGW : List (comma separated in []) of SGI addresses per RAN used as 
            Gateway for the AppServer.
    $APNs : List (comma separated in []) of APNs per RAN
        $enbnumber : Total number of eNBs in all RANs
    $noofscenarios : Maximum Number of RANs used
    $S1U_DEV : List (comma separated in []) of DPDK device for eNB S1U 
        interface per RAN (DPDK device definition see /opt/ng4t/etc/ports.conf)
    $AS_DEV : List (comma separated in []) of DPDK device for AppServers 
        interface per RAN (DPDK device definition see /opt/ng4t/etc/ports.conf)

    Update '{ng40_root_dir}/commonconf/networkelement.conf' in NG40 to configure
        for following:

    Section [MME-ENB]
    MCC : Mobile Country Code. Same as configure for MME and IMSIs. 
    MNC : Mobile Network Code. Same as configure for MME and IMSIs. 

    Section [ENBs]
    ENBs[0].TRANSPORT[0].SCTP_PORT : eNB SCTP port.

    Update '{ng40_root_dir}/commonconf/subscriber.conf' in NG40 to configure for
    following:
    
    [Subscriber]
    group[0].ki : Subscriber Secret used for all Subscriber
    
    Section [SubscriberProfile]
    profile[0].op : Operator Code
    profile[0].opc_flag : Configure if profile[0].op is the ciphered or unciphered OP (Set to: OP not equal OPc)
                
============
PROVISIONING
============

1. Add Test Data to Cassandra

    (a) Go to Cassandra Server/VM
    
    (b) Adding User Equipment (UEs)

        On the Cassandra server, the 
        {installation_root}/db_docs/data_provisioning_users.sh script can be used 
        to add one or more user equipment entries in the HSS database.
        Syntax:
        #./data_provisioning_users.sh <IMSI> <MSISDN> <APN> <Key> <No of UEs>
        <Cassandra_Server_IP>
    
        The script takes six parameters.

            IMSI - the first IMSI in the range to add. Each subsequent IMSI will be
                added by incrementing the value.
            MSISDN - the first MSISDN in the range to add.  Each subsequent MSISDN
                    will be added by incrementing the value.
                    **NOTE: the MSISDN must be 10 digits long**
            APN - the APN to be associated with each entry.
            KEY - the equipment key.
            NUMBER_OF_USERS - the total number of entries to add.
            CASSANDRA_IP - the IP address of the Cassandra server (same as the
                        <Cassandra_Server_IP> configured above).

        The following example will add 25 entries:
        #./data_provisioning_users.sh 208014567891234 1122334455 apn1 465B5CE8B199B49FAA5F0A2EE238A6BC 25 192.168.112.60

    (c) Adding Core Servers

        On the Cassandra VM, the 
        {installation_root}/db_docs/data_provisioning_mme.sh script can be 
        used to add server entries into the database. The primary purpose is to 
        identify MME's to the HSS.  It is also used to identify other servers to 
        the HSS such as an SMS router. The script takes 6 parameters.
        Syntax:
        ./data_provisioning_mme.sh <ID> <ISDN> <HOST> <REALM> <UE
        Reachability> <Cassandra_Server_IP>

        ID - the unique numeric ID of the server. The ID values typically 
             start at 1.
        ISDN - the ISDN associated with the server. This required for the MME 
               entry.
        HOST - the fully qualified Diameter Identity of the server.
        REALM - the Diameter Realm of the server.
        UEREACHABILITY - indicates the UE reachability value that will be 
                         returned during subsequent HSS processing.
        CASSANDRA_IP - the IP address of the Cassandra server (same as the 
                       <Cassandra_Server_IP> configured above).

        Here are a couple of examples:

        #./data_provisioning_mme.sh 1 19136246000 mme.localdomain localdomain 1 192.168.112.60
        #./data_provisioning_mme.sh 1 19136246000 smsrouter.test3gpp.net test3gpp.net 0 192.168.112.60

    
    (c) Go to HSS server/VM
    
    (d) Calculate the OPc value for each UE (User Equipment).
        IMP: Whenever UE configuration is changed as in step (a) above, 
        following steps command be executed on HSS.
        On the HSS server run the following command:

            #cd {installation_root}/mme
            #./bin/hss -j conf/hss.json --onlyloadkey
    
2. NG40 provisioning
    (a) IMSI and MSISDN settings
        For UEs configured on C3PO setup, configure NG40 settings as follows:
        In file <ng40_root_dir>/subscriber.def.ilepc, add following fields as 
        per configuration in section "PROVISIONING"-> 1 ->(b)
        
        $IMSI - First IMSI value added in Cassandra.
        $MSISDN - First MSISDN value added in Cassandra.
        $IMEI - First IMEISV for first UE, incremented by 100. No need to change


    (c) If <key> in the "PROVISIONING" -> 1 -> (b) is changed then update 
        <ng40_root_dir>/commonconf/subscriber.conf with new key as following 

        ...
        group[0].ki=465B5CE8B199B49FAA5F0A2EE238A6BC
        ...
    
    (d) Number of UEs setting
        Configure test script in NG40 for number of UEs, transaction rate.
        E.g. update following fields in '<ng40_root_dir>/test/mppsshort.cfg' file.

       ...
       set $numran 1 # Number of RANs to start
       set $subs 25 # To set 25 number of UEs under test. At least 25 subscriber * Number of RANs need to be configured
       set $totalrate 100 # To set transaction rate per second.
       set $pps 900000 # To set Packets Per Second to generate.        
       ...

================
RUN C3PO MODULES
================
    
A] Start control and data plane.
    Following are steps for ngic setup.
    1. Start DP
        #cd {ngic_installation_root}/dp
        #./run.sh

    2. Start CP
        #cd {ngic_installation_root}/cp
        #./run.sh

B] Start Cassandra
    
    Cassandra runs as service hence no need to start it every time. Service starts
    when cassandra server boots up. Verify that cassandra is running with command:

        #nodetool status
    
    If Cassandra is not running then start with command:
        #service cassandra start
    
C] Run the HSS

    To run the HSS application, use the following command on the HSS server:

        #cd {installation_root}/hss
        #./bin/hss -j conf/hss.json
  
D] Run the MME

E] Start ng40 test
    #cd {ng40_installation_root}/test
    #ng40test tc_userplane_mpps.ntl mppsshort.cfg