Index: /trunk/doc/manual/en_US/user_AdvancedTopics.xml =================================================================== --- /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_AdvancedTopics.xml (revision 35193) @@ -482,102 +482,4 @@ - - Custom external authentication modules - - As described in , VirtualBox supports - arbitrary external modules to perform authentication. When the - authentication method is set to "external" for a particular VM, - VirtualBox calls the library that was specified with - VBoxManage setproperty vrdeauthlibrary. - This library will be loaded by the VM process on demand, i.e. when the - first RDP connection is made by an external client. - - External authentication is the most flexible as the external - handler can both choose to grant access to everyone (like the "null" - authentication method would) and delegate the request to the guest - authentication component. When delegating the request to the guest - component, it will still be called afterwards with the option to - override the result. - - An authentication library is required to implement exactly one - entry point: - - #include "VBoxAuth.h" - -/** - * Authentication library entry point. Decides whether to allow - * a client connection. - * - * Parameters: - * - * pUuid Pointer to the UUID of the virtual machine - * which the client connected to. - * guestJudgement Result of the guest authentication. - * szUser User name passed in by the client (UTF8). - * szPassword Password passed in by the client (UTF8). - * szDomain Domain passed in by the client (UTF8). - * fLogon Boolean flag. Indicates whether the entry point is called - * for a client logon or the client disconnect. - * clientId Server side unique identifier of the client. - * - * Return code: - * - * AuthResultAccessDenied Client access has been denied. - * AuthResultAccessGranted Client has the right to use the - * virtual machine. - * AuthResultDelegateToGuest Guest operating system must - * authenticate the client and the - * library must be called again with - * the result of the guest - * authentication. - */ -AuthResult AUTHCALL AuthEntry( - const char *szCaller, - PVRDPAUTHUUID pUuid, - VRDPAuthGuestJudgement guestJudgement, - const char *szUser, - const char *szPassword - const char *szDomain - int fLogon, - unsigned clientId) -{ - /* process request against your authentication source of choice */ - return AuthResultAccessGranted; -} - - A note regarding the UUID implementation of the first argument: - VirtualBox uses a consistent binary representation of UUIDs on all - platforms. For this reason the integer fields comprising the UUID are - stored as little endian values. If you want to pass such UUIDs to code - which assumes that the integer fields are big endian (often also called - network byte order), you need to adjust the contents of the UUID to e.g. - achieve the same string representation. The required changes - are: - - reverse the order of byte 0, 1, 2 and 3 - - - - reverse the order of byte 4 and 5 - - - - reverse the order of byte 6 and 7. - - Using this conversion you will get identical results - when converting the binary UUID to the string representation. - - The second arguments contains information about the guest - authentication status. For the first call, it is always set to - AuthGuestNotAsked. In case the function - returns AuthResultDelegateToGuest, a - guest authentication will be attempted and another call to the method is - made with its result. This can be either granted / denied or no - judgement (the guest component chose for whatever reason to not make a - decision). In case there is a problem with the guest authentication - module (e.g. the Additions are not installed or not running or the guest - did not respond within a timeout), the "not reacted" status will be - returned. - Index: /trunk/doc/manual/en_US/user_BasicConcepts.xml =================================================================== --- /trunk/doc/manual/en_US/user_BasicConcepts.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_BasicConcepts.xml (revision 35193) @@ -735,5 +735,5 @@ Under the "Remote display" tab, if the VirtualBox Remote - Display Extension (VRDE) is installed, you can enable the RDP server + Display Extension (VRDE) is installed, you can enable the VRDP server that is built into VirtualBox. This allows you to connect to the virtual machine remotely with any standard RDP viewer, such as @@ -741,5 +741,5 @@ Windows or, on Linux systems, the standard open-source rdesktop program. These features - are described in detail in . + are described in detail in . Index: /trunk/doc/manual/en_US/user_Frontends.xml =================================================================== --- /trunk/doc/manual/en_US/user_Frontends.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_Frontends.xml (revision 35193) @@ -6,5 +6,5 @@ - Remote display (VRDP support) + VirtualBox Remote Desktop Extension (VRDE) VirtualBox can display virtual machines remotely. This allows you to @@ -63,5 +63,5 @@ The port can be changed either in the "Display" settings of the graphical user interface or with - --vrdpport option of the + --vrdeport option of the VBoxManage modifyvm command. You can specify a comma-separated list of ports or ranges of ports. Use a dash @@ -135,5 +135,5 @@ - VBoxHeadless, the VRDP-only server + VBoxHeadless, the remote desktop server While any VM started from the VirtualBox Manager is capable of @@ -142,5 +142,5 @@ the first place. In particular, if you are running servers whose only purpose is to host VMs, and all your VMs are supposed to run remotely - over VRDP, then it is pointless to have a graphical user interface on + over VRDE, then it is pointless to have a graphical user interface on the server at all -- especially since, on a Linux or Solaris host, the VirtualBox manager comes with dependencies on the Qt and SDL libraries, @@ -150,5 +150,5 @@ VirtualBox therefore comes with yet another front-end called VBoxHeadless, which produces no visible - output on the host at all, but instead only delivers VRDP data. + output on the host at all, but instead only delivers VRDE data. Before VirtualBox 1.6, the headless server was called VBoxVRDP. For the sake of backwards @@ -184,12 +184,12 @@ Note that when you use VBoxHeadless to start a VM, since the - headless server has no other means of output, the built-in RDP server + headless server has no other means of output, the VRDE server will always be enabled, regardless of whether you - have enabled the VRDP server in the VM's settings. If this is + have enabled the VRDE server in the VM's settings. If this is undesirable (for example because you want to access the VM via ssh only), start the VM like - this:VBoxHeadless --startvm <uuid|name> --vrdp=offTo - have the VRDP server use the setting from the VM configuration, as the - other front-ends would, use this:VBoxHeadless --startvm <uuid|name> --vrdp=config + this:VBoxHeadless --startvm <uuid|name> --vrde=off + To use the setting from the VM configuration, as the + other front-ends would, use this:VBoxHeadless --startvm <uuid|name> --vrde=config @@ -202,5 +202,6 @@ create a virtual machine, establish an RDP connection and install a guest operating system -- all without having to touch the headless - server. All you need is the following: + server. VirtualBox extension packages with the VRDP server must be + installed. All you need is the following: @@ -336,8 +337,8 @@ - RDP authentication - - For each virtual machine that is remotely accessible via RDP, you - can individually determine if and how RDP connections are + VRDE authentication + + For each virtual machine that is remotely accessible via VRDE, you + can individually determine if and how client connections are authenticated. @@ -348,5 +349,5 @@ The "null" method means that there is no authentication at - all; any client can connect to the VRDP server and thus the + all; any client can connect to the VRDE server and thus the virtual machine. This is, of course, very insecure and only to be recommended for private networks. @@ -422,9 +423,10 @@ default "external authentication module with any other module. For this, VirtualBox provides a well-defined interface that allows you to write - your own authentication module; see for details. - - - + your own authentication module. This is described in detail in the + VirtualBox Software Development Kit (SDK) reference; please see for details. + + + RDP encryption @@ -470,8 +472,8 @@ - - Multiple VRDP connections - - The built-in RDP server of VirtualBox supports simultaneous + + Multiple connections to the VRDP server + + The VRDP server of VirtualBox supports simultaneous connections to the same running VM from different clients. All connected clients see the same screen output and share a mouse pointer and @@ -482,16 +484,16 @@ - + Multiple remote monitors To access two or more remote VM displays you have to enable the - RDP multiconnection mode (see ). + VRDP multiconnection mode (see ). The RDP client can select the virtual monitor number to connect to using the domain logon parameter (-d). If the parameter ends with - @ followed by a number, the VirtualBox - RDP server interprets this number as the screen index. The primary guest + @ followed by a number, VirtualBox + interprets this number as the screen index. The primary guest screen is selected with @1, the first secondary screen is @2, etc. @@ -506,8 +508,8 @@ - + VRDP video redirection - Starting with VirtualBox 3.2, the RDP server can redirect video + Starting with VirtualBox 3.2, the VRDP server can redirect video streams from the guest to the RDP client. Video frames are compressed using the JPEG algorithm allowing a higher compression ratio than @@ -515,5 +517,5 @@ compression ratio by lowering the video quality. - Video streams in a guest are detected by the RDP server + Video streams in a guest are detected by the server automatically as frequently updated rectangular areas. Therefore, this method works with any guest operating system without having to install @@ -529,16 +531,28 @@ The quality of the video is defined as a value from 10 to 100 percent, as is common with JPEG compression. The quality can be changed - using the following command: VBoxManage modifyvm "VM name" --vrdpvideochannelquality 75 - - - + using the following command: VBoxManage modifyvm "VM name" --vrdevideochannelquality 75 + + + VRDP customization - Starting with VirtualBox 3.2.10, it is possible to disable display + Starting with VirtualBox 4.0, it is possible to disable display output, mouse and keyboard input, audio, remote USB or clipboard in the VRDP server. - The following commands change corresponding server - settings: + The following commands change corresponding server settings: + + VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1 +VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1 + + To reenable a feature use a similar command without the trailing + 1. For example: VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay= + + Note that with earlier releases of VirtualBox (3.2.10 or more recent 3.2 versions), + the following commands change corresponding server settings: VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1 Index: /trunk/doc/manual/en_US/user_Glossary.xml =================================================================== --- /trunk/doc/manual/en_US/user_Glossary.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_Glossary.xml (revision 35193) @@ -319,7 +319,7 @@ and keyboard and mouse input events are sent from the client. VirtualBox contains an enhanced implementation of the relevant - standards called "VirtualBox RDP" (VRDP), which is largely compatible - with Microsoft's RDP implementation. See for - details. + standards implemented as a VirtualBox Remote Desktop Extension (VRDE), + which is largely compatible with Microsoft's RDP implementation. + See for details. @@ -427,4 +427,14 @@ + VRDE + + + VirtualBox Remote Desktop Extension -- allows remot eaccess to + virtual machines. VirtualBox provides a VRDE, which implements Remote + Desktop Protocol (see RDP). + + + + VRDP Index: /trunk/doc/manual/en_US/user_Introduction.xml =================================================================== --- /trunk/doc/manual/en_US/user_Introduction.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_Introduction.xml (revision 35193) @@ -353,5 +353,5 @@ systems other than Windows (even in text mode) and does not require application support in the virtual machine either. The VRDE is - described in detail in . + described in detail in . On top of this special capacity, VirtualBox offers you more @@ -363,5 +363,5 @@ it includes an easy-to-use SDK which allows you to create arbitrary interfaces for other methods of authentication; see - for details. + for details. @@ -533,5 +533,5 @@ VirtualBox Remote Desktop Protocol (VRDP) support; see - . + . Index: /trunk/doc/manual/en_US/user_Technical.xml =================================================================== --- /trunk/doc/manual/en_US/user_Technical.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_Technical.xml (revision 35193) @@ -369,6 +369,6 @@ VBoxHeadless, a VM front end which does not directly provide any video output and keyboard/mouse - input, but allows redirection via VRDP; see . + input, but allows redirection via VirtualBox Remote Desktop Extension; + see . Index: /trunk/doc/manual/en_US/user_Troubleshooting.xml =================================================================== --- /trunk/doc/manual/en_US/user_Troubleshooting.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_Troubleshooting.xml (revision 35193) @@ -879,5 +879,5 @@ input (moving the mouse over a menu is the most obvious situation) and output. This is because this RDP client collects input for a certain - time before sending it to the VRDP server built into VirtualBox. + time before sending it to the RDP server. The interval can be decreased by setting a Windows registry key to Index: /trunk/doc/manual/en_US/user_VBoxManage.xml =================================================================== --- /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35192) +++ /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35193) @@ -311,5 +311,5 @@ Audio: disabled (Driver: Unknown) Clipboard Mode: Bidirectional -VRDP: disabled +VRDE: disabled USB: disabled @@ -833,5 +833,5 @@ - Serial port, audio, clipboard, VRDP and USB settings + Serial port, audio, clipboard, remote desktop and USB settings The following other hardware settings are available through @@ -936,21 +936,21 @@ modifyvm: - --vrdp on|off: With the + --vrde on|off: With the VirtualBox graphical user interface, this enables or disables the - built-in VRDP server. Note that if you are using + VirtualBox remote desktop extension (VRDE) server. Note that if you are using VBoxHeadless (see ), VRDP output is always enabled. - - - - --vrdpport + linkend="vboxheadless" />), VRDE is enabled by default. + + + + --vrdeport default|<ports>: A port or a range of ports - the VRDP server can bind to; "default" or "0" means port 3389, the + the VRDE server can bind to; "default" or "0" means port 3389, the standard port for RDP. You can specify a comma-separated list of ports or ranges of ports. Use a dash between two port numbers to - specify a range. The VRDP server will bind to one of available ports from the specified list. Only one machine can use a given port at a time. For - example, the option --vrdpport + example, the option --vrdeport 5000,5010-5012 will tell the server to bind to one of following ports: 5000, 5010, 5011 or 5012. @@ -958,7 +958,7 @@ - --vrdpaddress <IP + --vrdeaddress <IP address>: The IP address of the host network - interface the VRDP server will bind to. If specified, the VRDP + interface the VRDE server will bind to. If specified, the server will accept connections only on the specified host network interface. @@ -973,14 +973,15 @@ - --vrdpmulticon on|off: This - enables multiple VRDP connections to the same VRDP server; see - . - - - - --vrdpreusecon on|off: This - specifies the VRDP server behavior when multiple connections are - disabled. When this option is enabled, the VRDP server will allow - a new client to connect and drop the existing connection. When + --vrdemulticon on|off: This + enables multiple connections to the same VRDE server, if the server + supports this feature; see + . + + + + --vrdereusecon on|off: This + specifies the VRDE server behavior when multiple connections are + disabled. When this option is enabled, the server will allow + a new client to connect and will drop the existing connection. When this option is disabled (this is the default setting), a new connection will not be accepted if there is already a client @@ -989,14 +990,14 @@ - --vrdpvideochannel on|off: - This enables VRDP video acceleration; see . - - - - --vrdpvideochannelquality - <percent>: Sets the image quality for VRDP - video acceleration; see . + --vrdevideochannel on|off: + This enables video redirection, if it is supported by the VRDE server; + see . + + + + --vrdevideochannelquality + <percent>: Sets the image quality for + video redirection; see . @@ -1188,5 +1189,5 @@ determines whether the machine will be started in a window (GUI mode, which is the default) or whether the output should go through - VBoxHeadless, with VRDP enabled or not; + VBoxHeadless, with VRDE enabled or not; see for more information. The list of types is subject to change, and it's not guaranteed that all types are @@ -1205,17 +1206,8 @@ - vrdp + headless - Starts a VM showing a GUI window, with its graphics card - output accessible by an RDP client. - - - - - headless - - - Starts a VM without a window for remote RDP display + Starts a VM without a window for remote display only. @@ -1336,14 +1328,14 @@ - vrdp on|off lets you enable or - disable the built-in VRDP server. + vrde on|off lets you enable or + disable the VRDE server, if it is installed. - vrdpport default|<ports> - changes the port or a range of ports that the VRDP server can bind to; + vrdeport default|<ports> + changes the port or a range of ports that the VRDE server can bind to; "default" or "0" means port 3389, the standard port for RDP. For details, see the description for the - --vrdpport option in --vrdeport option in .