User Tools

Site Tools


nova-rdp-api

Nova RDP Support API

Nova currently provides support for VNC and SPICE graphical consoles. VNC in particular is the protocol employed natively by most popular hypervisors supported by Nova. Microsoft Hyper-V in this context is a remarkable exception, as it employs the Remote Desktop Protocol (RDP) for graphical console access, based on Open Specifications and implemented by various open source projects.

Here's an example video showing an HTML5 RDP console based on FreeRDP.


Getting an RDP console URL

This requires a public API which is symmetric with the VNC and SPICE ones.

Get an RDP console URL: V2 API

Verb URI Description
GET /servers/{id}/action Gets the URL for accessing the RDP console.

Normal Response Code(s): 200

Error Response Code(s): badRequest (400), itemNotFound (404), buildInProgress (409)

Example. Get RDP console URL request: XML

<?xml version="1.0" encoding="UTF-8"?>
<os-getRDPConsole type="rdp-html5" />

Example. Get RDP console URL request: JSON

{
    "os-getRDPConsole": {
        "type": "rdp-html5"
    }
}

Example. Get RDP console URL response: XML

<?xml version='1.0' encoding='UTF-8'?>
    <console>
        <type>rdp-html5</type>
        <url>http://example.com:6083/?token=f9906a48-b71e-4f18-baca-c987da3ebdb3</url>
    </console>

Example. Get RDP console URL response: JSON

{
    "console": {
        "type": "rdp-html5",
        "url": "http://example.com:6083/?token=f9906a48-b71e-4f18-baca-c987da3ebdb3&title=dafa(75ecef58-3b8e-4659-ab3b-5501454188e9)"
    }
}

Get an RDP console URL: V3 API

Verb URI Description
GET /v3/servers/{id}/action Gets the URL for accessing the RDP console.

Normal Response Code(s): 200

Error Response Code(s): badRequest (400), itemNotFound (404), buildInProgress (409)

Example. Get RDP console URL request: XML

<?xml version="1.0" encoding="UTF-8"?>
<get_rdp_console type="rdp-html5" />

Example. Get RDP console URL request: JSON

{
    "get_rdp_console": {
        "type": "rdp-html5"
    }
}

Example. Get RDP console URL response: XML

Same output as in the V2 API example

Example. Get RDP console URL response: JSON

Same output as in the V2 API example


Getting console connection details

Nova includes internally the required proxy solutions for VNC (novnc, xvpvnc) and SPICE, but this is not the case for RDP. Beside that, it's also desirable to leave to third party the ability to choose a custom graphical console UI solution not necessarily included with Nova. A public API has been provided to retrieve the relevant information by providing a valid console authentication token.

Get console connection info: V2 API

Verb URI Description
GET /os-console-auth-tokens/{token_id} Gets the connection info for the specified console authentication token.

Normal Response Code(s): 200

Error Response Code(s): badRequest (400), itemNotFound (404)

Example. Get console connection request: XML

<?xml version="1.0" encoding="UTF-8"?>
<os-getConsoleConnectInfo/>

Example. Get console connection request: JSON

{
    "os-getConsoleConnectInfo": null
}

Example. Get console connection response: XML

<?xml version='1.0' encoding='UTF-8'?>
<console>
    <instance_uuid>b48316c5-71e8-45e4-9884-6c78055b9b13</instance_uuid>
    <host>localhost</host>
    <port>3389</port>
    <internal_access_path>51af38c3-555e-4884-a314-6c8cdde37444</internal_access_path>
</console>

Example. Get console connection response: JSON

 {
    "console": {
        "instance_uuid": "b48316c5-71e8-45e4-9884-6c78055b9b13",
        "host": "localhost",
        "port": 3389,
        "internal_access_path": "51af38c3-555e-4884-a314-6c8cdde37444"
    }
} 

Get console connection info: V3 API

Verb URI Description
GET /v3/os-console-auth-tokens/{token_id} Gets the connection info for the specified console authentication token.

Normal Response Code(s): 200

Error Response Code(s): badRequest (400), itemNotFound (404)

Example. Get console connection request: XML

<?xml version="1.0" encoding="UTF-8"?>
<get_console_connect_info/>

Example. Get console connection request: JSON

{
    "get_console_connect_info": null
}

Example. Get console connection response: XML

Same output as in the V2 API example

Example. Get console connection response: JSON

Same output as in the V2 API example

nova-rdp-api.txt · Last modified: 2014/05/07 02:28 (external edit)