Difference between revisions of "JSON API for YateUCN Configuration"

From YateBTS
Jump to: navigation, search
Line 4: Line 4:
 
You will send it multiple times to an UCN server, depending on the type of node you want to configure.
 
You will send it multiple times to an UCN server, depending on the type of node you want to configure.
 
* ucn (MSC/VLR, SGSN, GGSN, MME, SGW, PGW)
 
* ucn (MSC/VLR, SGSN, GGSN, MME, SGW, PGW)
 +
You can use it to configure all types of settings or you can use specific requests for each features: '''set_diameter_node''', '''set_mme_sgsn''', etc.
  
 
== Request: '''set_node''' ==
 
== Request: '''set_node''' ==

Revision as of 11:49, 10 October 2017

YateUCN replaces the MSC/VLR, SGSN, GGSN and GMSC of a 2G network, and the MME,SGW and PGW of a 4G network.

The main request to configure a node is set_node. You will send it multiple times to an UCN server, depending on the type of node you want to configure.

  • ucn (MSC/VLR, SGSN, GGSN, MME, SGW, PGW)

You can use it to configure all types of settings or you can use specific requests for each features: set_diameter_node, set_mme_sgsn, etc.

Request: set_node

This request is used to configure a YateUCN server. It mainly configures the SS7/Diameter settings, but also access points and other information needed for the ps/eps features.

The main parameters are:

  • node_type: "ucn" / "stp"
  • ss7
    • local - information about the local node (the actual YateUCN server that you are configuring). The information about the local node is organized in:
      • common - common settings that will probably be used for all the subnodes. Some of this information are network settings while others are equipment specific
      • vlr/sgsn/mme/pgw (only when configuring node_type ucn). You can override some of the common parameters. Ex: set a different gt for the VLR subnode.
    • linksets - configure the linksets and links to the STP
    • gt_route - configure the GT routes table
  • access_points - configure the access points that the customers are allowed to use
  • tunnels - configure the tunnels (GTP) used the the ps/eps service
  • diameter
    • identities - configure local nodes
    • listeners - configure the listeners
    • connections - configure outgoing connections
  • s1ap
    • common - configure common/default S1AP parameters
    • listeners - configure the S1AP listeners
  • restart - boolean. Whether to restart now and apply settings sent in the same request or previously
{  "node_type": "ucn" / "stp",
   "ss7": {
     "local": {
       "common": {
         "dialect": "ITU" / "ANSI",
         "netindicator": "national" / "reservednational" / "international",
         "pointcode": NNN,  // integer representation, range depends on dialect
         "gt": "NNNNNNNNNN",
         "ip": ["x.x.x.x" / "xx:xx::xx"],  // Local IP address for signaling protocols
         "nnsf_node": NNN,  // Node Resource Index for Network Node Selection Function
         "nnsf_bits": N,  // Bits used from (P)TMSI for NNSF
         "ip_gtp": "x.x.x.x" / "xx:xx::xx",  // IP address for GTP
         "def_smsc": "NNNNNNNNNN",  // optional GT to use instead of malformed SMSC
         "empty_begin": false / true / 0 / 1,  // start SMS delivery with an empty TCAP Begin
       },
       "vlr": {  // parameters and overrides for UCN/VLR+MSC only
         "nnsf_node": NNN,  // optional override
         "nnsf_bits": N,  // optional override
       },
       "sgsn": {  // parameters and overrides for UCN/SGSN only
         "nnsf_node": NNN,  // optional override
         "nnsf_bits": N,  // optional override
       },
       "mme": {  // parameters and overrides for UCN/MME only
         "identity": {
            "plmns": [ "NNNNN", "NNNNNN", ... ],  // List of MCCMNC
            "tac": NNN,
            "group": NNN,
            "code": NN,  // LTE specific nnsf_node override, must be unique per group, 0 to 255
            "name": "some-name-here",  // optional
         },
       },
       "pgw": {  // parameters and overrides for UCN/PGW only
         "ip_gtp_c": "x.x.x.x" / "xx:xx::xx",  // IP address for GTP-C
         "ip_gtp_u": "x.x.x.x" / "xx:xx::xx",  // IP address for GTP-U
       },
     },
     "linksets": [
	{ "type": "MTP3" / "M3UA",
         "pointcode": NNN,  // integer representation, range depends on dialect
         "route": [ NNN, NNN, ... ],  // List of PCs in integer representation to route through this STP
         "gt": [ "NNNNN", "NNNNN", ... ],  // List of GT prefixes to route through this STP, can be just [ "*" ]
         "ip": ["x.x.x.x" / "xx:xx::xx"],  // Remote IP address
         "aspid": NNN               // only for M3UA
         "contexts": N, N, ...      // only for M3UA, comma separated list of context numbers
         "links": [
            {  "port": ,     // port on the adjacent node
               "local_ip": []  // optional local IP address
               "local_port": // optional local port number
            },
            // ... other links if necessary
         ]
       },
       // ... linkset for the second STP 
     ],
  }
  "access_points": [                 // only for ucn node
       {  "name": "ap-name-without-dots",
          "tunnel": "name-of-the-tunnel",  // must match one entry in tunnels - see below
          "aliases": "comma, separated, list, of.other.names",  // optional
          "ipv": "ipv4" / "ipv6" / "ipv4v6" / "ipv4_or_v6" / "ipv6_or_v4",
          "qos": "xx xx xx",  // optional, 2G/3G specific, hex encoded
          "qci": N,  // optional, 4G specific, 1 to 9
          "ordered_delivery": false / true / 0 / 1,  // not recommended - advanced setting
          "charging": false / true / 0 / 1,
          // Protocol Configuration Options
          "primary_dns_ipv4": "x.x.x.x",  // optional but likely needed
          "secondary_dns_ipv4": "x.x.x.x",  // optional
          "primary_dns_ipv6": "xx:xx::xx",  // optional but likely needed for IPv6 capable APs
          "secondary_dns_ipv6": "xx:xx::xx",  // optional
          "p_cscf_ipv4": "x.x.x.x",  // optional but likely needed for AP "ims"
          "p_cscf_ipv6": "xx:xx::xx",  // optional
          "mtu_ipv4": NNNN,  // optional, 552 to 9216
          "restart_cdr":NNNNNNN, // optional, 300 to 2678400 seconds. Interval at which CDRs should be restarted for an active data session
          "interim_cdr":NNNNN // optional, 30 to 86400 seconds. Interval at which interim CDRs should be generated for an active data session
       },
       // ... arbitrary number of APs
    ],
  "tunnels": [                           // only for ucn node
       {  "name": "name-of-the-tunnel",
          "ipv4_gtpu_address": "x.x.x.x",  // optional
          "ipv6_gtpu_address": "xx:xx::xx",  // optional, but at least one of them should be present
          "dscp": "normal" / "expedited" / ... ,  // search in Socket.cpp for: // DSCP
          "dscp_per_qci": { // optional
             "N": "normal" / "expedited" / ... ,  // N can be 1 to 9
             "N": "normal" / "expedited" / ... ,  // can be repeated multiple times
          },
          // End user IP allocation pools
          "pool_ipv4": [  // optional
             "x.x.x.x-x.x.x.x",
             "x.x.x.x-x.x.x.x",  // can be repeated multiple times
          ],
          "pool_ipv6": [  // optional
             "xx:xx:xx:xx::-xx:xx:xx:xx::",  // only the upper 64 bits can be specified
             "xx:xx:xx:xx::-xx:xx:xx:xx::",  // can be repeated multiple times
          ],
       },
       // ... arbitrary number of tunnels
    ]
}


Set S1AP example:

"s1ap": {
   "common": {
      "streams": 5
   },
   "listeners": [
      {
         "local_ip": "192.168.168.194",
      },
      {
         "local_ip": "192.168.168.194",
         "local_port": 36413,
         "streams": 2,
         "payload": 19,
         "dscp": "expedited",
         "sctp_params": {
           "max_retrans": 3
         }
      }
   ]
}

Request: set_mme_sgsn_node

This request allows configuring of the MME/SGSN node of the YateUCN.

{
 "request" : "set_mme_sgsn_node",
 "node" : "ucn",
 "params" : {
   "identity": {
     "plmns": [NNNNN, NNNNN, ...], // Comma separated array of supported PLMNs in MCCMNC form
     "group": NNNNN, // 0 - 65535
     "tac": NNNNN, // 0 - 65535
     "code": NNN,  // 0 -255
     "name": "Name_of_MME" // string
   },
   "integrity_algos": "128-EIA1,128-EIA2,128-EIA3", // Comma separated list of integrity algorithms activated for NAS
   "cipher_algos": "EEA0,128-EEA1,128-EEA2,128-EEA1", // Comma separated list of encryption algorithms activated for NAS
   "nnsf_bits": NN, // integer, 0 - 10. Number of P-TMSI bits allocated for Network Node Selection Function
   "nnsf_node": NNN, // integer, 0 - 225 when SGSN is combined with MME, 0 - (2^nnsf_bits - 1) otherwise. Node index for Network Node Selection Function
   "restart_cdr": NNNNNNN, // optional, 300 to 2678400 seconds. Interval at which CDRs should be restarted for an active data session
   "interim_cdr": NNNNN // optional, 30 to 86400 seconds. Interval at which interim CDRs should be generated for an active data session
   "local_pdn": true/false, // Only allow the embedded PGW to provide any PDN connectivity
   "extra_params": { // extra parameters used for configuration
     "enb_cipher_algos":"EEA0,128-EEA1,128-EEA2,128-EEA1", // Comma separated list of encryption algorithms to announce to the ENBs
     "enb_integrity_algos":"128-EIA1,128-EIA2,128-EIA3", // Comma separated list of integrity algorithms to announce to the ENBs
   },
   "gtps":{ // configure S1 and S5 GTP interfaces
     "s1":[ // configure S1 (RAN-side) GTP interfaces. Array of GTP endpoints that are to be configured. Setting at least one GTP endpoint is mandatory
       {
         "name":"ran", // optional, name of endpoint to be created
         "ipv4_gtpu_address" : "x.x.x.x", // IPv4 address for GTP-u
         "ipv4_gtpc_address" : "x.x.x.x", // IPv4 address for GTP-c. If not provided, it will be the same address as for GTP-u
         "ipv6_gtpu_address" : "xx:xx::xx",  // IPv6 address for GTP-u
         "ipv6_gtpc_address" : "xx:xx::xx",  // IPv6 address for GTP-c. 
         "dscp" : "normal" / "expedited" / ... ,  // search in Socket.cpp for: // DSCP
         "gtpc_dscp: "normal" / "expedited" / ... ,  // same as DSCP, overrides "dscp" value for GTP-c
         "gtpu_dscp: "normal" / "expedited" / ... ,  // same as DSCP, overrides "dscp" value for GTP-u
         "gtpc_v2":true
       },
       {
         ... // other S1 GTP endpoint
       }
     ],
     "s5": [ // configure S5 GTP interfaces. Array of GTP endpoints to be configured. If a remote PGW is used for PDN connectivity, at least one GTP endpoint is mandatory
       {
         "name": "core", // optional, name of endpoint to be created
         "ipv4_gtpu_address" : "x.x.x.x", // IPv4 address for GTP-u
         "ipv4_gtpc_address" : "x.x.x.x", // IPv4 address for GTP-c. If not provided, it will be the same address as for GTP-u
         "ipv6_gtpu_address" : "xx:xx::xx",  // IPv6 address for GTP-u
         "ipv6_gtpc_address" : "xx:xx::xx",  // IPv6 address for GTP-c. 
         "dscp" : "normal" / "expedited" / ... ,  // search in Socket.cpp for: // DSCP
         "gtpc_dscp: "normal" / "expedited" / ... ,  // same as DSCP, overrides "dscp" value for GTP-c
         "gtpu_dscp: "normal" / "expedited" / ... ,  // same as DSCP, overrides "dscp" value for GTP-u
         "gtpc_v2":true
       },
       {
         ... // other S5 GTP endpoint
       }
     ]
   }
 }
}


The same configuration can be obtained through the set_node request by putting the all parameters of the params object from the set_mme_sgsn_node in a mme_sgsn object, except for extra_params. See example below:

{
 "request" : "set_node",
 "node" : "ucn",
 "params": {
   "mme_sgsn":{
     "identity": {
       "plmns": [NNNNN, NNNNN, ...],
       "group": NNNNN,
       "tac": NNNNN,
       ...
     },
     "nnsf_bits": NN, 
     "nnsf_node": NNN, 
     "restart_cdr": NNNNNNN, 
     "interim_cdr": NNNNN, 
     "local_pdn": true/false, 
     "gtps":{
       "s1":[
         {
           "ipv4_gtpu_address" : "x.x.x.x",
           "dscp" : "expedited"
         },
         {
           "name":"other",
           "ipv4_gtpu_address" : "x.x.x.x",
           "dscp" : "expedited",
           "gtpc_v2":true
         }
       ],
       "s5": [
         {
           "ipv4_gtpu_address" : "x.x.x.x",
           "ipv4_gtpc_address" : "x.x.x.x",
           "dscp" : "expedited"
         }
       ]
     }
   },
   "extra_params":{
     "enb_cipher_algos":"EEA0",
     "enb_integrity_algos:""128-EIA1,128-EIA2"
   }
 }
}

Request: set_numbers

Only for the UCN node.

{  "type": "roaming"/"handover",
   "numbers": [ .. ]
}