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:

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.

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:

Text enclosed in <> such as <Cassandra_Server_IP> requires input specific to your setup, such as an IP address
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.

Go to Cassandra server server/VM.

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

 #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

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

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

 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

(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

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

c3po
c3po copied to clipboard

Metadata

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

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

============ PROVISIONING

================ RUN C3PO MODULES

← Metadata

Owner

Metadata

c3po c3po copied to clipboard

Metadata

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

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

============ PROVISIONING

================ RUN C3PO MODULES

← Metadata

Owner

Metadata

c3po
c3po copied to clipboard