First draft RDP.md on RDP control, from guest-agent to XenCenter

Signed-off-by: Thomas Sanders <thomas.sanders@citrix.com>

features/RDP.md

@@ -0,0 +1,89 @@
+---
+title: RDP control
+layout: default
+---
+### Purpose
+
+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.
+
+As of early December 2014 the xapi and XenCenter parts are in development; the guest agent part has been there for a long while but has a bug.
+
+### The guest agent
+
+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 xenstore node
+`/local/domain/N/control/feature-ts = 1`
+when it starts up: this indicates support for the rest of the functionality described below.
+
+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.
+
+### XAPI etc.
+
+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 pair of messages (function calls) for asking the guest agent to turn RDP on and off.
+They are named `beg_rdp_on` and `beg_rdp_off` respectively (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.
+
+### XenCenter
+
+#### Behaviour on older XenServer versions that do not support RDP control
+
+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".
+
+1.    When tools are not installed:
+  *       As of XenCenter 6.5, the RDP button is absent.
+2.    When tools are installed but RDP is not switched on in the guest:
+  1.      If "Enable Remote Desktop console scanning" is on:
+    *         The RDP button is present but greyed out. (It seems to sometimes read "Switch to Remote Desktop" and sometimes read "Looking for guest console...": I haven't yet worked out the difference).
+    *         We scan the RDP port to detect when RDP is turned on
+  2.      If "Enable Remote Desktop console scanning" is off:
+    *         The RDP button is enabled and reads "Switch to Remote Desktop"
+3.    When tools are installed and RDP is switched on in the guest:
+  1.      If  "Enable Remote Desktop console scanning" is on:
+    *         The RDP button is enabled and reads "Switch to Remote Desktop"
+    *         If "Automatically switch" is on, we switch to RDP immediately we detect it
+  2.      If "Enable Remote Desktop console scanning" is off:
+    *         As above, the RDP button is enabled and reads "Switch to Remote Desktop"
+
+#### Proposed new behaviour on XenServer versions that support RDP control
+
+1. This new XenCenter behaviour is only for XenServer versions that support RDP control: behaviour with older servers should be unchanged.
+2. There should be no change in the behaviour for Linux guests, either PV or HVM varieties: this must be tested.
+3. We should never scan the RDP port; instead we should watch for a change in the relevant variable in guest_metrics.
+4. The option "Enable Remote Desktop console scanning" should change to read "Enable Remote Desktop console scanning (XenServer 6.5 and earlier)"
+5. The option "Automatically switch to the Remote Desktop console when it becomes available" should be enabled even when "Enable Remote Desktop console scanning" is off.
+6. When tools are not installed:
+  * As above, the RDP button should be absent.
+7. When tools are installed but RDP is not switched on in the guest:
+  * The RDP button should be enabled and read "Turn on Remote Desktop"
+  * If pressed, it should launch a dialog with the following wording: "Would you like to turn on Remote Desktop in this VM, and then connect to it over Remote Desktop?   [Yes] [No]"
+  * That button should turn on RDP, wait for RDP to become enabled, and switch to an RDP connection. It should do this even if "Automatically switch" is off.
+8. When tools are installed and RDP is switched on in the guest:
+  * The RDP button should be enabled and read "Switch to Remote Desktop"
+  * If "Automatically switch" is on, we should switch to RDP immediately
+  * There is no need for us to provide UI to switch RDP off again
+9. We should also test the case where RDP has been switched on in the guest before the tools are installed.
+
+### Open question
+
+In the design as described above, if someone switches RDP on or off using the normal controls provided in Windows, then the guest agent will not notice, and therefore neither will XenServer or XenCenter.
+
+Therefore we should do one of
+* Make the guest agent update xenstore spontaneously when the RDP service changes state (either by polling or registering for some event)
+* Poll or query the guest agent from xapi
+* Add another new call to XenAPI to ask the guest agent to update the value that indicates whether RDP is running, then make XenCenter call this in the circumstances in which it used to scan the RDP port.
+
+Of those options, the first seems least inelegant.