JSON API for YateHSS/HLR Configuration

Request: get_node_type

Retrieve installed node type and software version on an equipment.
In special cases you might have more components on a single physical machine.

Request

{ “request”:”get_node_type” }

Example response when multiple nodes are installed:

“code”:0,”node_type”:[{“type”:”hss”,”version”:”1.4-1″},{“type”:”stp”,”version”:”0.1-1″},{“type”:”ucn”,”version”:”0.1-1″}]}

Request: get_node_config

Retrieve the specific node configurations (packaged and generated) as a tarball.
Note: In case of success the response Content-Type is application/octet-stream

Request parameters:

Example

{ “request”:”get_node_config”, “node”:”hss” }

Request: get_net_address

Retrieve configured interfaces and ip addresses per equipment:

Ex request:
 { “request”:”get_net_address”,”node”:”satsite”,”params”:”net_address”}
Ex response:
 { “code”:0,
   “net_address”:[
       {“interface”:”eno1″,
        “ethernet”:”94:DE:80:7B:36:FA”,
        “ipv4”:[{“address”:”192.168.168.208″,”netmask”:”255.255.255.0″}],
        “ipv6”:[{“address”:”fe80::96de:80ff:fe7b:36fa”,”prefixlen”:64}],
        “mtu”:1500
        }
   ]
}

Request: get_node_logs

Retrieve the logs of the specific node as text.
Note: In case of success the response Content-Type is text/plain

Request parameters:

Parameters:

Example

{ “request”:”get_node_logs”,
  “node”:”hss”,
  “params”: {
    “level”: “info”,
    “lines”: 20
  }
}

Request: set_node

This request is used to configure the SS7/Diameter/etc settings for a YateHSS/HLR server.

The main parameters are:

  • local – information about the local node (the actual YateHSS/HLR server that you are configuring). The information about the local node is organized in:
    • common – common settings for the network but also equipment specific information
  • linksets – configure the linksets and links to the STP
  • gt_route – configure the GT routes table
  • local – information about the local node (the actual YateHSS/HLR server that you are configuring). The information about the local node is organized in:
    • common – common settings for the network but also equipment specific information
  • identities – configure local nodes
  • listeners – configure the listeners
  • connections – configure outgoing connections
  • common – configure clustering node(s)
  • hss – configure clustering data used by HSS

Example:

{
 “node_type”: “hss”,
 “restart” : boolean,
 “ss7”: {
   “local”: {
      “common”: {
        “dialect”: “ITU” / “ANSI”,
        “netindicator”: “national” / “reservednational” / “international”,
        “pointcode”: NNN,                   // Local pointcode, integer representation, range depends on dialect
        “gt”: [“NNNNNNNNNN”, …],        // List of local GT. The first element is the GT we are sending from
        “hlr”: “NNNNN…”,                   // Optional, HLR number (GT) returned in Update Location
        “msisdn”: [“ABC”,”DEF”, …],        // List of MSISDN prefixes to which the HLR will respond
        “ip”: [“x.x.x.x” / “xx:xx::xx”],        // Array of Local IP address for signaling protocols. Array or comma separated list
        “sccp_tt”: boolean,                     // Optional, use Translation Type in SCCP messages, defaults to false
        “sccp_pc”: boolean,                    // Optional, use Point Code in SCCP source address, defaults to false
     },
  },
  “linksets”: [
     {
        “type”: “M2PA” / “M3UA”,
        “pointcode”: NNN,                     // Adjacent point code, integer representation, range depends on dialect
        “route”: [ NNN, NNN, … ],            // Optional list of PCs in integer representation to route through this STP
                                               // the string “default” may be used as point code to indicate a default route
                                                // e.g. route: [23, “default”]
         “links”: [                           // M2PA: list of links. M3UA: 1 entry with connection data
             {
                “ip”: [“x.x.x.x” / “xx:xx::xx”],// Array of Remote IP address. Array or comma separated list
                “port”: ,                         // Integer: 1-65535. Port on the adjacent node
                “local_ip”: [“”],                   // Optional local IP address (use common if missing)
                “local_port”: ,                   // Optional. Integer: 1-65535. Local port number,
                                                   // ignored for M3UA. Otherwise: use remote port as default if missing
                “dscp”: “”,                     // Optional socket DSCP (string or integer)
                “sctp_params”: {              // Optional SCTP params. All params are optional.
                                                 // All integer params are unsigned. See lksctp.conf for info
                “rto_initial”: NNN,
                “rto_min”: NNN,
                “rto_max”: NNN,
                “max_retrans”: NNN,
                “hb_interval”: NNN,
                “hb_enabled”: boolean,
                “sack_delay”: NNN,
                “sack_freq”: NNN,
             },
         },
          // … other links if necessary
      ],
      // M3UA only
       “aspid”: NNN,                        // Optional ASP identifier (unsigned 32 bit)
       “contexts”: [N, N, …],            // Optional list of routing context numbers (unsigned 32 bit)
       “traffic”: “unused” / “override” / “loadshare” / “broadcast”, // Optional traffic type
       “network_appearance”: NNN,          // Optional network appearance (unsigned 32 bit)
   },
   // … linkset for the second STP
],
“gt_route”: [                               // GT route table
    {
        “pc”: NNN,                         // Remote point code (must a configured one if there is no default route)
        “prefix”: [“NNNNN”, …],          // List of GT prefixes to route to this PC, can be just [ “*” ]
     },
     // … other routes
   ],

},
“diameter”: {
  “local”: {
     “common”: {
         “relay_route_priority”: NNN,          // Optional default route priority for remote nodes advertising
                                                 // relay application. Negative: disable. Defaults to 100
      },
   },
   “identities”: [
      {
          “node”: “example.com/hss.example.com”, // Node identity (realm(domain_name)/host(host_name))
          “role”: “role_name”,           // Optional name of special role of this node
          “default_priority”: NN,         // Optional priority to use this node if no other matches. Default 0 (disabled)
          “default_realm_priority”: NN,      // Optional priority to use this node if only realm matches. Default 0 (disabled)
      },
     // … other identities
  ],
  “listeners”: [
      {
          “local_ip”: [],                        // Array of Local IP to bind to.
          “local_port”: ,                        // Optional local port number, protocol default port will be used if missing
          “ipv6only”: boolean,               // Optional. Accept IPv6 only connections. Ignored if local_ip is IPv4
          “dscp”: “”,                    // Optional socket DSCP (string or integer)
          “sctp_params”: {                 // Optional SCTP params. All params are optional.
                                             // All integer params are unsigned. See lksctp.conf for info
             “rto_initial”: NNN,
             “rto_min”: NNN,
             “rto_max”: NNN,
             “max_retrans”: NNN,
             “hb_interval”: NNN,
             “hb_enabled”: boolean,
             “sack_delay”: NNN,
             “sack_freq”: NNN,
          },
           “accept”: [                            // Optional, configure accept rule(s)
                                                      // If present and not empty it will restrict the list of local nodes
                                                     // handled by this listener
                                                     // All identities will be handled by this listener if accept is empty
             {
                “node”: “node_name”,          // Node to accept, must be a configured identity
                “accept_node”: [],              // Optional remote node(s) to accept
                                                // String: RegExp to match node(s) to accept
                                              // Array: Only remote nodes matching it will be accepted. If present and not empty only listed remote nodes will be accepted
                “default_route”: NNN, // Optional default route priority for accepted connections
             },
              // … other rules
           ],
        },
        // … other listeners
     ],
     “connections”: [
        {
           “node”: “node_name”,             // Local identity. The name of a node configured in identities
           “remote_host”: “FQDN”,            // Diameter remote (peer) host name
           “ip”: [],                            // Optional IP address to connect to. Remote host will be used if missing
           “port”: ,                         // Optional port to connect to. Protocol default will be used if missing
           “local_ip”: [],                 // Optional local IP to bind on
           “dscp”: “”,                    // Optional socket DSCP (string or integer)
           “sctp_params”: {                  // Optional SCTP params. All params are optional.
                                             // All integer params are unsigned. See lksctp.conf for info
               “rto_initial”: NNN,
               “rto_min”: NNN,
               “rto_max”: NNN,
               “max_retrans”: NNN,
               “hb_interval”: NNN,
               “hb_enabled”: boolean,
               “sack_delay”: NNN,
               “sack_freq”: NNN,
            },
            “default_route”: NNN,                    // Optional default route priority
         },
         // … other connections
     ],
  },
  “cluster”: {
  “common”: {
     “local_ip”: “x.x.x.x” / “xx:xx::xx” / “::”, // Conditional. Local address to bind
     “local_port”: NNN,                       // Optional. Integer: [1..65535]. Port to listen. Defaults to 5028
     “secret”: “password”,                   // Optional. Authentication password. Must be the same for all cluster nodes
                                               // Must not contain leading or trailing space/tab characters
     “remote”: [                           // Optional. List of nodes to connect to
       {
          “nodename”: “node_name”,         // Remote HSS node name. Must not contain the ‘=’ char
          “ip”: “x.x.x.x” / “xx:xx::xx”,      // Remote IP address
          “port”: NNN,                           // Optional. Integer: [1..65535]. Port to connect to. Defaults to 5028
       },
       // … other nodes if necessary
     ]
   },
    “hss”: {
      “nodename”: “node_name”,             // Optional. Informative only. HSS local node name. Empty value will be ignored
      “db_nodes”: NNN,                      // Conditional. Maximum number of HSS nodes in cluster. Range: [1..100]
      “db_index”: NNN,                    // Conditional. Current node index. Range: [1..db_nodes]
      “db_limit”: NNN,                     // Optional, integer. Range 10 – 500, default 100. Maximum records chunk size when synchronizing from remote nodes.
      “conflict_disc”:boolean            // Optional, boolean, default false. Disconnect from remote node on database configuration conflict
    }
  },
}

Notes:

  • HSS node name will be removed from remote nodes
  • A non empty list of remote nodes indicates clustering is enabled
  • Clustering enabled:
    • local_ip is mandatory. It may be empty to listen on all IPv4 addresses
    • db_nodes and db_index are mandatory
    • The length of remote nodes list can’t be greater than db_nodes
  • Clustering not enabled: db_nodes and db_index are linked: the presence of one of them make mandatory the other one
  •  

Set Diameter example:

{
    “identities”: [
       {
          “node”: “example.com/hss.example.com”,
          “default_realm_priority”: 100,
       },
       {
          “node”: “example.com/hss2.example.com”,
       },
    ],
    “listeners”: [
        {
           “local_ip”: “127.0.0.1”,
           “local_port”: 7000,
           “sctp_bindx”: [“192.168.168.194”],
           “accept”: [
              {
                  “node”: “example.com/hss.example.com”,
                  “accept_node”: [“example.com/proxy.example.com”],
              }
          ],
       },
       {
           “local_ip”: “192.168.168.194”,
       },
    ],
    “connections”: [
       {
           “node”: “example.com/hss.example.com”,
           “remote_host”: “proxy.example.com”,
           “ip”: “127.0.0.1”,
           “port”: 9000,
       },
    ],
}

Request: set_operator

This request creates or updates a mobile operator profile. It is expected that an MVNE would create one profile per MVNO.

{ “request”:”set_operator”,
  “params”: {
    “operator_id”: “”, // required for editing, don’t set for creation
    “name”:””, // required when creating a new operator
    “home”: {
         “gts”: [ “…”, ], // array of GT prefixes to match home (non-roaming) VPLMN nodes
         “realms”: [ “…”, ], // array of home Diameter realms
         “gmscs”: [ “…”, ], // array of home GMSC GTs
         “smscs”: [ “…”, ] // array of home SMSC GTs
     },
     “visited”: {
         “prefix”: 5-15, // number of digits to consider for VPLMN identification
         “xprefixes”:[“…”] // array of extra prefixes added by roaming hubs
         “check”: “http://url/template”, // called to validate roaming in a new PLMN
         “hook”: “http://url/template”, // called to notify roaming in a new PLMN
         “check_always”: true/false,     // always call the check URL
         “check_default” “…”          // default action on unknown check response
      }
   }
}

The HTTP hooks support the following parameters:

  • imsi: 15 digit IMSI of the SIM
  • net: GT prefix or Diameter realm
  • roaming: boolean
  • type: cs, ps or ims
  • node: vlr, sgsn, mme, mme-sgsn or cscf
  • proto: MAP or DIAMETER
  • imei: 15 digit IMEI or 16 digit IMEISV
  • old: GT prefix or Diameter realm
  • tech: geran, utran or e-utran
  • plmn: PLMN ID
  • gt: full GT of the node if applicable
  • oprefix: operator routing prefix (one of xprefixes)
  • nprefix: unprefixed GT (with the xprefix removed)

The check URL is expected to return a one-line text/plain answer:

The hook URL ignores any answer or failure. Its purpose is to trigger some multi-IMSI mechanism.

Example:

{ “request”:”set_operator”,
  “params”: {
    “name”:”Default”,
    “home”: {
        “gts”: [ “882” ],
        “realms”: [ “example.com” ],
        “gmscs”: [ “8820003” ],
        “smscs”: [ “8820003” ]
    },
    “visited”: {
         “prefix”: 8,
         “xprefixes”:[“998″,”999”]
         “check”: “http://127.0.0.1/check.php?imsi=${imsi}&imei=${imei}&node=${node}&net=${net}“,
         “hook”: “http://127.0.0.1/hook.php?imsi=${imsi}&imei=${imei}&net=${net}&old=${old}
    }
  }
}

Our solutions