Colin Dean
Version 1
Last updated 24 November 2009
This document describes the XVP extensions to the RFB Protocol published by RealVNC Ltd. The extensions are also fully documented in the community version of the RFB protocol specification.
These extensions were devised by Colin Dean to allow VNC-based clients to perform administrative operations (shutdown, reboot and reset) on virtual machines hosted on Citrix® XenServer, via the Xen VNC Proxy (xvp). These extensions are supported by xvp, and its associated client, xvpviewer, and also by recent versions of the ggivnc viewer.
The extensions are intended to be sufficiently general that they could be implemented at the server end for other virtualisation platforms, not just Citrix XenServer.
A new security type is used by xvp:
| Number | Name |
|---|---|
| 22 | xvp |
and also a new pseudo-encoding:
| Number | Name |
|---|---|
| -309 | xvp |
and message type:
| Number | Name |
|---|---|
| 250 | xvp |
The message is used client to server and server to client, with the same format:
| No.of bytes | Type [Value] | Description |
|---|---|---|
| 1 | U8 250 | message type |
| 1 | padding | |
| 1 | U8 1 | xvp extension version |
| 1 | U8 | xvp message code |
The following xvp message codes are defined:
| Value | Name | Direction |
|---|---|---|
| 0 | XVP_FAIL | server to client |
| 1 | XVP_INIT | server to client |
| 2 | XVP_SHUTDOWN | client to server |
| 3 | XVP_REBOOT | client to server |
| 4 | XVP_RESET | client to server |
The xvp security type is used to implement XVP authentication, which is similar to standard VNC authentication, except that the client specifies a user name and a target name. This is used so that the server can implement (a) different passwords for different users, and (b) multiplexing of consoles for multiple target systems on a single TCP port.
Once XVP authentication has been selected, and before any challenge is sent from the server to the client, the client sends a message to the server of the form:
| No.of bytes | Type [Value] | Description |
|---|---|---|
| 1 | U8 | user-length |
| 1 | U8 | target-length |
| user-length | U8 array | user-string |
| target-length | U8 array | target-string |
Either (or both) lengths may be zero, and the corresponding string omitted, to indicate a request for access as a default user and/or to a default target, although the server is not obliged to allow defaults.
The authentication dialog is then completed exactly as when using VNC authentication, i.e. with a challenge from server to client followed by a password-encrypted response from client to server.
The server should send a challenge, and await a response, even if it considers the user and/or target information to be invalid. This is to (a) limit the scope for malicious attacks which could otherwise probe for a valid user/target combination without having to know any passwords, and (b) allow a meaningful security result to be returned to the client (if using RFB version 3.8 or later).
A client wishing to use the xvp extensions must signal this to the server by including the xvp pseudo-encoding (-309) in a SetEncodings message.
A server not supporting the xvp extensions will ignore this, but one that does support these extensions replies with a message of type xvp (250) and message code XVP_INIT. The server must specify in this message the highest xvp extension version it supports: the client may assume that the server supports all versions from 1 up to this value.
Only after this message has been received by the client, may it use the operation messages below. The client is free to use any xvp extension version supported by the server. Currently, only version 1 is defined.
A client, having established that the server supports the xvp extensions, may request the server to perform an operation by sending a message of type xvp (250) with one of the following message codes:
| Operation | Message Code |
|---|---|
| shutdown VM cleanly | XVP_SHUTDOWN |
| reboot VM cleanly | XVP_REBOOT |
| reset VM abruptly | XVP_RESET |
Whereas the shutdown and reboot operations should be performed by the server in a way that allows the VM to save its data gracefully, the reset operation is intended to be analogous to ripping out and re-inserting the VM's power plug, and may result in data corruption (for instance, requiring a filesystem repair on restart).
If the server is unable to perform the operation, it must send a message of type xvp (250) with message code XVP_FAIL, and the same xvp extension version as included in the client's request. The client should convey failure to the user (for example, by displaying an alert, "Operation Failed").
If the server successfully performs the requested operation, it does not send a specific reply (success should be obvious from the contents of the VM's console framebuffer displayed by the client).
XVP is Copyright © 2009 Colin Dean, and is free software, distributable under the terms of the GNU General Public License. More information is available on the project web site: http://www.xvpsource.org/
Thanks to Peter Rosin for making me realise I needed to write this document, and for adding XVP support to ggivnc.
The VNC protocol was originally developed by the RealVNC team while at Olivetti Research Ltd / AT&T Laboratories Cambridge, UK. Thanks to Tristan Richardson of RealVNC for registering the XVP extensions.
Citrix® is a registered trademark and XenCenter™ a trademark of Citrix Systems, Inc.