JSON API for YateUCN Configuration

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_node, 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” : {
   // MME parameters
    “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
    “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
    “cs_plmn”:”NNNNN”, // string, optional. PLMN Identity for CS combined attach. Defaults to selected LTE PLMN
    “cs_lac”:NNNNN, // integer, 0 – 65533. Location Area Code for CS combined attach
    // SGSN parameters
    “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
     // Common MME/SGSN paramters
    “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
      },
      {
           … // 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”: [ .. ]
}

Our solutions