Controller Southbound RESTful API

Using API

User Authentication

To access the controller Southbound API, the user must already be authenticated and possess a valid access token. Nodes pass this token to the controller in the HTTP headers of their requests. An example of such a token placed in a HTTP-header is

Authentication: b438e13737144ca8a39cad03b8986dcb

Additional Parameter Format

Any additional parameters are passed to the controller in the JSON format. The format is specified in HTTP headers of the requests.

Content-Type: application/json

Version

All requests use the format shown below. The base prefix is the same in all the requests.

/api/<version>/<url>

The current implementation uses the value v1 in the Version field of the prefix. As such, all requests have the prefix shown below.

/api/v1/

Node Identifier

The node CGA address is used as a node identifier in all requests. The CGA is passed to the controller as a hexadecimal string 32 bytes long.

Southbound API for Agent

The Southbound API allows the agent to perform the operations shown in the table below.

Operation URL Description
Host Management    
GET /host/0/init Get initial config from cntlr
PUT /host/<nodeid> Register host on cntlr
POST /host/<nodeid> Send keepalive msg to cntlr
DELETE /host/<nodeid> Unregister host on cntlr
Connection Management    
PUT </host/<nodeid>/conn Register connection on cntlr
Endpoint Management    
PUT /host/<nodeid>/service Register svc endpoint cntlr

GET /host/0/init

Method returns initial configuration for the node, for example

{
    "auth_login_url": "https://1.2.3.4/identity/api/login/",
    "auth_openid_url": "https://1.2.3.4/identity/openid/",
    “auth_params” {
        "nonce": "n-0S6_WzA2Mj",
        "state": "af0ifjsldkj",
        "redirect_uri": "https://1.2.3.4/login_callback/",
        "response_type": "id_token token",
        "client_id": "430213",
        "scope": "openid profile domain roles provider_id"
    }
}

After receiving this information, the node sends the registration request to auth_url (Identity Service) providing the username, password and domain alongside with the auth_params.

PUT /host/<nodeid>

Request Structure

An example of this request is shown below.

{
    “cga_params”: “<hex_string>”,
    “cga_sign”: “<hex_string>”,
    “cfg”: {
        "ip":"8.8.8.10",
        "hostname": "testhostname",
        “noderole”: 0,
        “ports”: [
            {“number”: 1, “name”: “eth0”, “hwaddr”: “aabbccddeeff”, “admin_status”: 1},
            {“number”: 2, “name”: “eth1”, “hwaddr”: “ffeeddccbbaa”, “admin_status”: 2},
        ]
    },
    "cfg_hash": "abc123456789",
    “net”: {},
    "net_hash": "9876654321abc"
}

cga_params

Parameter cga_params is a hexadecimal string of concatenated octets as shown below.

Name Description Length (b)
Modifier used in CGA address gen 128
Collision Count used in CGA address gen 8
Public Key RSA public key in DER format variable

cga_sign

Controller must validate CGA Sign with Public Key. Signed string has the format

Name Description Length (b)
CGA Address   128
CGA Params includes Public Key 200+

cga_hash

Parameter cfg_hash is a MD5 hash calculated by the agent. It is calculated on the serialized string comprising IP address, hostname, noderole, ports. For example

"ip":"8.8.8.10",
"hostname": "testhostname",
“noderole”: 0,
“ports”: [
    {“number”: 1, “name”: “eth0”, “hwaddr”: “aabbccddeeff”, “admin_status”: 1},
    {“number”: 2, “name”: “eth1”, “hwaddr”: “ffeeddccbbaa”, “admin_status”: 2}
]

net_hash

Parameter net_hash is a MD5 hash of the object net described later.

Response

The response HTTP codes to this request are the following:

  • HTTP 200 - host registered successfully
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)

An example of the response on a successful registration (HTTP 200) is shown below.

{
    “host_id”: “123456789abc”,
    “lldp_key”: “dfasadfadsf”,
    “keepalive_period”: 600
}

POST /host/<nodeid>

Keep-alive Request

This request is used to send keep-alive message or update some parameters.

A request example is shown below.

{
    "cfg_hash": "abc123456789",
    "net_hash": "123456789abc"
}

Keep-alive Response

The response HTTP codes to this request are the following:

  • HTTP 200 - processed successfully (no command present)
  • HTTP 202 - accepted, but the processing has not been completed (a command present)
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)

An example of the response on a successful keep-alive update (HTTP 202) is shown below.

{
    “host_id”: “123456789abc”,
    “keepalive_period”: 600,
    “cfg_refresh”: 1,
    “net_refresh”: 1
}

Configuration Management Request

When the parameter cfg_refresh or net_refresh has the value of 1 in the response, the host repeats the keep-alive request but, this time, sending the block of requested configuration. For example

{
    “cfg”: {
        "ip":"8.8.8.10",
        "hostname": "testhostname",
        “ports”: [
            {“number”: 1, “name”: “eth0”, “hwaddr”: “aabbccddeeff”, “admin_status”: 1},
            {“number”: 2, “name”: “eth1”, “hwaddr”: “ffeeddccbbaa”, “admin_status”: 2}
        ]
    },
    "cfg_hash": "abc123456789",
    “net”: [
        “conn”: [
            {“local_conn”: 12, “local_port”: 8, “remote_cga”, “<hex_string>”, “status”: 1},
            {...}
        ]
    ],
    "net_hash": "123456789abc"
}

Configuration Management Response

An example of the response on a successful keep-alive update (HTTP 200), that does not require any new information from the host, is shown below.

{
    “host_id”: “123456789abc”,
    “keepalive_period”: 600,
    “cfg_refresh”: 0,
    “net_refresh”: 0
}

DELETE /host/<nodeid>

Request

This request calls on for host unregistration. The request has no body.

Response

The response HTTP codes to this request are the following:

  • HTTP 200 - processed successfully
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)

PUT /host/<nodeid>/conn

This is a request for link registration.

Content of the request and response to it depends on link registration state: preauth or auth.

Preauth Request

An example of the request in the Preauth state is shown below.

{
    “stage”: “preauth”,
    “nonce”: “112233445566”,
    “remote_cga”: “<hex_string>”,
    “local_port” 8,
    “local_conn”: 12
}

Where

  • stage - link establishment phase (can be “preauth” or “auth”)
  • nonce - Nonce value from the SeND packet (in hex string format)
  • remote_cga - CGA IP Address of remote node (in hex string format)
  • local_port - local port identifier (integer)
  • local_conn - local connection identifier (integer)

Preauth Response

The response in a normal case is HTTP 200 with empty body.

All the possible responses to this request are:

  • HTTP 200 - processed successfully
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)
  • HTTP 406 - connection validation failed (e.g., invalid nonce, local port not found, remote_cga not registered)

Auth Request

An example of the request in the Auth state is shown below.

{
    “stage”: “auth”,
    “nonce”: “112233445566”,
    “remote_cga”: “<hex_string>”,
    “local_port”: 15
}

Auth Response

An example of the response on a successful Auth request (HTTP 200) is shown below.

{
    “success”: true,
    “data”: {
        “nonce”: “112233445566”,
        “remote_port”: 33,
        “remote_portname” “eth1”,
        “remote_conn”: 122,
        “remote_node_role”: “host”,
        “remote_domain”: “domainA”
    }
}

All the possible responses to this request are:

  • HTTP 200 - processed successfully
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)
  • HTTP 406 - connection validation failed (e.g., invalid nonce, local port not found, remote_cga not registered)

Southbound API for Engine

The Southbound API allows switches to perform the operations shown in the table below.

Operation URL Description
Host Management    
GET /switch/0/init Get initial config from cntlr
PUT /switch/<nodeid> Register node on cntlr
POST /switch/<nodeid> Send node keepalive msg to cntlr
DELETE /switch/<nodeid> Unregister node on cntlr
Connection Management    
PUT /switch/<nodeid>/conn register connection on cntlr

GET /switch/0/init

TBD

PUT /switch/<nodeid>

Request

An example of switch registration request is shown below.

{
    “cfg”: {
        "ip":"8.8.8.10",
        "hostname": "testhostname",
        “noderole”: 0,
        “ports”: [
             {“dp”: “<datapath_id>”,
              “ports”: [
                   {“number”: 1, “name”: “eth0”, “hwaddr”: “aabbccddeeff”, “admin_status”: 1},
                   {“number”: 2, “name”: “eth1”, “hwaddr”: “ffeeddccbbaa”, “admin_status”: 2}
                ]
             }
       ]
    },
    "cfg_hash": "abc123456789",
    “net”: {},
    "net_hash": "9876654321abc"
}

cfg_hash

Parameter cfg_hash is a MD5 hash calculated by the supervisor. It is calculated on the serialized string comprising IP address, hostname, noderole, ports. For example

"ip":"8.8.8.10",
"switchname": "testswitchname",
“noderole”: 0,
“ports”: [
    {“dp”: “<datapath_id>”,
     “ports”: [
            {“number”: 1, “name”: “eth0”, “hwaddr”: “aabbccddeeff”, “admin_status”: 1},
            {“number”: 2, “name”: “eth1”, “hwaddr”: “ffeeddccbbaa”, “admin_status”: 2}
        ]
    }
]

net_hash

Parameter net_hash is a MD5 hash of the object net described later.

Response

The response HTTP codes to this request are the following:

  • HTTP 200 - node registered successfully
  • HTTP 401 - unauthorized (token is not valid)
  • HTTP 403 - forbidden (user has no permissions on the requested node)
  • HTTP 404 - node not found (not registered)

An example of the response on a successful registration (HTTP 200) is shown below.