Difference between revisions of "JSON API for Configuration"

Latest revision as of 13:21, 26 November 2018

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:

• node: "hss"

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:

• node: "hss"

Parameters:

• level: Optional minimum log level: "mild" / "call" / "note" / "info" / "all", defaults to "warn". Can be numeric, between 6-10
• lines: Optional maximum number of lines to retrieve, range 10 - 1000, default 50

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:

• node_type: "hss"

• ss7
  • 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
• diameter
  • 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
• cluster
  • common - configure clustering node(s)
  • hss - configure clustering data used by HSS
• restart - boolean. Whether to restart now and apply settings sent in the same request or previously

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:

• For M3UA pointcode is optional. Either pointcode and/or route must be present
• HSS clustering:
  • 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,
      },
   ],
}