| Design document | |
|---|---|
| Revision | v2 |
| Status | released (XenServer 6.5 SP1) |
| Review | #12 |
To administer guest VMs it can be useful to connect to them over Remote Desktop Protocol (RDP). XenCenter supports this; it has an integrated RDP client.
First it is necessary to turn on the RDP service in the guest.
This can be controlled from XenCenter. Several layers are involved. This description starts in the guest and works up the stack to XenCenter.
This feature was completed in the first quarter of 2015, and released in Service Pack 1 for XenServer 6.5.
The XenServer guest agent installed in Windows VMs can turn the RDP service on and off, and can report whether it is running.
The guest agent is at https://github.com/xenserver/win-xenguestagent
Interaction with the agent is done through some Xenstore keys:
The guest agent running in domain N writes two xenstore nodes when it starts up:
/local/domain/N/control/feature-ts = 1/local/domain/N/control/feature-ts2 = 1This indicates support for the rest of the functionality described below.
(The “…ts2” flag is new for this feature; older versions of the guest agent wrote the “…ts” flag and had support for only a subset of the functionality (no firewall modification), and had a bug in updating .../data/ts.)
To indicate whether RDP is running, the guest agent writes the string “1” (running) or “0” (disabled) to xenstore node
/local/domain/N/data/ts.
It does this on start-up, and also in response to the deletion of that node.
The guest agent also watches xenstore node /local/domain/N/control/ts and it turns RDP on and off in response to “1” or “0” (respectively) being written to that node. The agent acknowledges the request by deleting the node, and afterwards it deletes local/domain/N/data/ts, thus triggering itself to update that node as described above.
When the guest agent turns the RDP service on/off, it also modifies the standard Windows firewall to allow/forbid incoming connections to the RDP port. This is the same as the firewall change that happens automatically when the RDP service is turned on/off through the standard Windows GUI.
xenopsd sets up watches on xenstore nodes including the control tree and data/ts, and prompts xapi to react by updating the relevant VM guest metrics record, which is available through a XenAPI call.
XenAPI includes a new message (function call) which can be used to ask the guest agent to turn RDP on and off.
This is VM.call_plugin (analogous to Host.call_plugin) in the hope that it can be used for other purposes in the future, even though for now it does not really call a plugin.
To use it, supply plugin="guest-agent-operation" and either fn="request_rdp_on" or fn="request_rdp_off".
See http://xapi-project.github.io/xen-api/classes/vm.html
The function strings are named with “request” (rather than, say, “enable_rdp” or “turn_rdp_on”) to make it clear that xapi only makes a request of the guest: when one of these calls returns successfully this means only that the appropriate string (1 or 0) was written to the control/ts node and it is up to the guest whether it responds.
Note that the current behaviour depends on some global options: “Enable Remote Desktop console scanning” and “Automatically switch to the Remote Desktop console when it becomes available”.