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”: [ .. ]
}