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.