Index: /trunk/doc/manual/Makefile.kmk
===================================================================
--- /trunk/doc/manual/Makefile.kmk (revision 35276)
+++ /trunk/doc/manual/Makefile.kmk (revision 35277)
@@ -132,4 +132,5 @@
user_KnownIssues.xml \
user_PrivacyPolicy.xml \
+ user_Security.xml \
user_Technical.xml \
user_ThirdParty.xml \
Index: /trunk/doc/manual/en_US/UserManual.xml
===================================================================
--- /trunk/doc/manual/en_US/UserManual.xml (revision 35276)
+++ /trunk/doc/manual/en_US/UserManual.xml (revision 35277)
@@ -58,4 +58,7 @@
xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+
Index: /trunk/doc/manual/en_US/user_Frontends.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Frontends.xml (revision 35276)
+++ /trunk/doc/manual/en_US/user_Frontends.xml (revision 35277)
@@ -6,10 +6,11 @@
- VirtualBox Remote Desktop Extension (VRDE)
-
- VirtualBox can display virtual machines remotely. This allows you to
- see the output of a virtual machine's window remotely on another computer
- and control the virtual machine from there, as if the virtual machine was
- running on that computer.
+ Remote display (VRDP support)
+
+ VirtualBox can display virtual machines remotely, meaning that a
+ virtual machine can execute on one machine even though the machine will be
+ displayed on a second computer, and the machine will be controlled from
+ there as well, as if the virtual machine was running on that second
+ computer.
For maximum flexibility, starting with VirtualBox 4.0, VirtualBox
@@ -19,10 +20,11 @@
be supplied by third parties with VirtualBox extension packages, which
must be installed separately from the base package. See for more information.
-
- Oracle provides support for the VirtualBox Remote Display Protocol
- (VRDP) in such a VirtualBox extension package. When this package is
- installed, VirtualBox versions 4.0 and later support VRDP the same way as
- earlier versions.
+ linkend="intro-installing" /> for more information.
+
+ Oracle provides support for the VirtualBox
+ Remote Display Protocol (VRDP) in such a VirtualBox extension
+ package. When this package is installed, VirtualBox versions 4.0 and later
+ support VRDP the same way as binary (non-open-source) versions of
+ VirtualBox before 4.0 did.
VRDP is a backwards-compatible extension to Microsoft's Remote
@@ -140,15 +142,17 @@
running virtual machines remotely, it is not convenient to have to run
the full-fledged GUI if you never want to have VMs displayed locally in
- 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 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,
- which is inconvenient if you would rather not have the X Window system
- on your server at all.
+ the first place. In particular, if you are running server hardware 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 the server at all -- especially since, on a Linux or
+ Solaris host, the VirtualBox manager comes with dependencies on the Qt
+ and SDL libraries. This is inconvenient if you would rather not have the
+ X Window system on your server at all.
VirtualBox therefore comes with yet another front-end called
VBoxHeadless, which produces no visible
- output on the host at all, but instead only delivers VRDE data.
+ output on the host at all, but instead only delivers VRDP data. This
+ front-end has no dependencies on the X Window system on Linux and
+ Solaris hosts.
Before VirtualBox 1.6, the headless server was called
VBoxVRDP. For the sake of backwards
@@ -157,13 +161,15 @@
- To start a virtual machine with VBoxHeadless, you have two
+ To start a virtual machine with
+ VBoxHeadless, you have two
options:
- You can use VBoxManage startvm "VM name" --type headless
- The extra --type option causes the
- VirtualBox core to use VBoxHeadless
- as the front-end to the internal virtualization engine.
+ You can use VBoxManage startvm "VM name" --type headlessThe
+ extra --type option causes
+ VirtualBox to use VBoxHeadless as
+ the front-end to the internal virtualization engine instead of the
+ Qt front-end.
@@ -173,5 +179,5 @@
follows:VBoxHeadless --startvm <uuid|name>
- This way of starting the VM has the advantage that you can see
+ This way of starting the VM is preferred because you can see
more detailed error messages, especially for early failures before
the VM execution is started. If you have trouble with
@@ -184,11 +190,11 @@
Note that when you use
VBoxHeadless to start a VM, since the
- headless server has no other means of output, the VRDE server
- will always be enabled, regardless of whether you
- have enabled the VRDE server in the VM's settings. If this is
- undesirable (for example because you want to access the VM via
+ headless server has no other means of output, the VRDP server will
+ always be enabled, regardless of whether you had
+ enabled the VRDP 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> --vrde=off
- To use the setting from the VM configuration, as the
+ this:VBoxHeadless --startvm <uuid|name> --vrde=offTo
+ have the VRDP server enabled depending on the VM configuration, as the
other front-ends would, use this:VBoxHeadless --startvm <uuid|name> --vrde=config
@@ -202,28 +208,28 @@
create a virtual machine, establish an RDP connection and install a
guest operating system -- all without having to touch the headless
- server. VirtualBox extension packages with the VRDP server must be
- installed. All you need is the following:
+ server. All you need is the following:
VirtualBox on a server machine with a supported host
- operating system; for the following example, we will assume a
- Linux server;
-
-
-
- an ISO file on the server, containing the installation data
- for the guest operating system to install (we will assume Windows
- XP in the following example);
-
-
-
- a terminal connection to that host over which you can access
- a command line (e.g. via telnet
- or ssh);
-
-
-
- an RDP viewer on the remote client; see
+
+
+
+ An ISO file accessible from the server, containing the
+ installation data for the guest operating system to install (we
+ will assume Windows XP in the following example).
+
+
+
+ A terminal connection to that host through which you can
+ access a command line (e.g. via
+ ssh).
+
+
+
+ An RDP viewer on the remote client; see above for examples.
@@ -240,8 +246,9 @@
Note that if you do not specify
--register, you will have to
- manually use the registervm command later.
+ manually use the registervm
+ command later.
Note further that you do not need to specify
- --ostype but doing so selects
+ --ostype, but doing so selects
some sane default values for certain VM parameters, for example
the RAM size and the type of the virtual network device. To get a
@@ -258,5 +265,5 @@
Create a virtual hard disk for the VM (in this case, 10GB in
- size) and register it with VirtualBox:VBoxManage createhd --filename "WinXP.vdi" --size 10000 --remember
+ size):VBoxManage createhd --filename "WinXP.vdi" --size 10000
@@ -267,5 +274,5 @@
- Set this newly created VDI file as the first virtual hard
+ Set the VDI file created above as the first virtual hard
disk of the new VM:VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
--port 0 --device 0 --type hdd --medium "WinXP.vdi"
@@ -293,5 +300,5 @@
You should now be seeing the installation routine of your
- guest operating system in the RDP viewer.
+ guest operating system remotely in the RDP viewer.
@@ -337,17 +344,16 @@
- VRDE authentication
-
- For each virtual machine that is remotely accessible via VRDE, you
+ RDP authentication
+
+ For each virtual machine that is remotely accessible via RDP, you
can individually determine if and how client connections are
- authenticated.
-
- For this, use VBoxManage modifyvm
- command with the --vrdeauthtype option;
- see for a general introduction.
- Three methods of authentication are available:
+ authenticated. For this, use VBoxManage
+ modifyvm command with the
+ --vrdeauthtype option; see for a general introduction. Three
+ methods of authentication are available:
The "null" method means that there is no authentication at
- all; any client can connect to the VRDE server and thus the
+ all; any client can connect to the VRDP server and thus the
virtual machine. This is, of course, very insecure and only to be
recommended for private networks.
@@ -356,57 +362,101 @@
The "external" method provides external authentication
- through a special authentication library.
-
- VirtualBox comes with three default libraries for external
- authentication:
+ through a special authentication library. VirtualBox ships with
+ two such authentication libraries:
- On Linux hosts,
- VBoxAuth.so authenticates
- users against the host's PAM system.
+ The default authentication library,
+ VBoxAuth, authenticates
+ against user credentials of the hosts. Depending on the host
+ platform, this means:
+
+ On Linux hosts,
+ VBoxAuth.so
+ authenticates users against the host's PAM
+ system.
+
+
+
+ On Windows hosts,
+ VBoxAuth.dll
+ authenticates users against the host's WinLogon
+ system.
+
+
+
+ On Mac OS X hosts,
+ VBoxAuth.dylib
+ authenticates users against the host's directory
+ service.
+ Support for Mac OS X was added in version
+ 3.2.
+
+
+
+
+ In other words, the "external" method per default
+ performs authentication with the user accounts that exist on
+ the host system. Any user with valid authentication
+ credentials is accepted, i.e. the username does not have to
+ correspond to the user running the VM.
- On Windows hosts,
- VBoxAuth.dll authenticates
- users against the host's WinLogon system.
+ An additional library called
+ VBoxAuthSimple performs
+ authentication against credentials configured in the
+ "extradata" section of a virtual machine's XML settings
+ file. This is probably the simplest way to get
+ authentication that does not depend on a running and
+ supported guest (see below). The following steps are
+ required:
+
+ Enable
+ VBoxAuthSimple with
+ the following command:
+
+ VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"
+
+
+
+ To enable the library for a particular VM, you
+ must then switch authentication to external:VBoxManage modifyvm <vm> --vrdeauthtype external
+
+ Replace
+ <vm> with the
+ VM name or UUID.
+
+
+
+ You will then need to configure users and
+ passwords by writing items into the machine's
+ extradata. Since the XML machine settings file, into
+ whose "extradata" section the password needs to be
+ written, is a plain text file, VirtualBox uses hashes
+ to encrypt passwords. The following command must be
+ used:VBoxManage setextradata <vm> "VBoxAuthSimple/users/<user>" <hash>
+
+ Replace
+ <vm> with the
+ VM name or UUID,
+ <user> with the
+ user name who should be allowed to log in and
+ <hash> with the
+ encrypted password. As an example, to obtain the hash
+ value for the password "secret", you can use the
+ following command:VBoxManage internalcommands passwordhash "secret"
+
+ This will print
+ "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b".
+ You can then use VBoxManage setextradata to store this
+ value in the machine's "extradata" section.
+
+ As example, combined together, to set the
+ password for the user "john" and the machine "My VM"
+ to "secret", use this command:VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
+ 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b
+
+
-
-
- On Mac OS X hosts,
- VBoxAuth.dylib
- authenticates users against the host's directory
- service.
- Support for Mac OS X was added in version
- 3.2.
-
-
-
-
- In other words, the "external" method per default performs
- authentication with the user accounts that exist on the host
- system. Any user with valid authentication credentials is
- accepted, i.e. the username does not have to correspond to the
- user running the VM.
-
-
-
- An additional library called
- VBoxAuthSimple performs
- authentication against credentials configured in the VM's extra
- data section. This is probably the simplest way to get
- authentication that does not depend on a running and supported
- guest (see below). In order to enable VBoxAuthSimple, issue
- VBoxManage setproperty vrdeauthlibrary
- "VBoxAuthSimple". To enable the library for a VM,
- switch authentication to external using VBoxManage
- modifyvm "VM name" --vrdeauthtype external. Last
- but not least, you have to configure users and passwords. Here is
- an example for the user "john" with the password "secret":
- VBoxManage internalcommands passwordhash
- "secret" This will give you the hash value
- "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
- which you set using VBoxManage setextradata "VM
- name" "VBoxAuthSimple/users/john"
- "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b".
+
@@ -414,14 +464,17 @@
Finally, the "guest" authentication method performs
authentication with a special component that comes with the Guest
- Additions; as a result, authentication is not performed with the
- host users, but with the guest user accounts. This method is
- currently still in testing and not yet supported.
+ Additions; as a result, authentication is not performed on the
+ host, but with the guest user
+ accounts.
+
+ This method is currently still in testing and not yet
+ supported.
In addition to the methods described above, you can replace the
- 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. This is described in detail in the
+ 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. This is described in detail in the
VirtualBox Software Development Kit (SDK) reference; please see for details.
@@ -440,5 +493,5 @@
RDP client does not perform any checks in order to verify the
identity of the server it connects to. Since user credentials can
- be obtained using a man in the middle (MITM) attack, RDP4
+ be obtained using a "man in the middle" (MITM) attack, RDP4
authentication is insecure and should generally not be
used.
@@ -475,5 +528,5 @@
Multiple connections to the VRDP server
- The VRDP server of VirtualBox supports simultaneous
+ The VRDP server of VirtualBox supports multiple simultaneous
connections to the same running VM from different clients. All connected
clients see the same screen output and share a mouse pointer and
@@ -495,11 +548,12 @@
(-d). If the parameter ends with
@ 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.
-
- The MS RDP6 client does not let you specify a separate domain
- name. Instead, use domain\username in
- the Username: field -- for example,
+ interprets this number as the screen index. The primary guest screen is
+ selected with @1, the first secondary
+ screen is @2, etc.
+
+ The Microsoft RDP6 client does not let you specify a separate
+ domain name. Instead, use
+ domain\username in the
+ Username: field -- for example,
@2\name.
name must be supplied, and must be the
@@ -517,12 +571,13 @@
compression ratio by lowering the video quality.
- 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
- additional software in the guest.
+ The VRDP server automatically detects video streams in a guest as
+ frequently updated rectangular areas. As a result, this method works
+ with any guest operating system without having to install additional
+ software in the guest; in particular, the Guest Additions are not
+ required.
On the client side, however, currently only the Windows 7 Remote
Desktop Connection client supports this feature. If a client does not
- support video redirection, the VRDP server uses regular bitmap
+ support video redirection, the VRDP server falls back to regular bitmap
updates.
@@ -530,6 +585,7 @@
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" --vrdevideochannelquality 75
+ percent, representing a JPEG compression level (where lower numbers mean
+ lower quality but higher compression). The quality can be changed using
+ the following command: VBoxManage modifyvm "VM name" --vrdevideochannelquality 75
@@ -537,9 +593,10 @@
VRDP customization
- 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:
+ With VirtualBox 4.0 it is possible to disable display output,
+ mouse and keyboard input, audio, remote USB or clipboard individually in
+ the VRDP server.
+
+ The following commands change corresponding server
+ settings:
VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
@@ -553,6 +610,7 @@
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:
+ These properties were introduced with VirtualBox 3.2.10. However,
+ in the 3.2.x series, it was necessary to use the following commands to
+ alter these settings instead:
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 35276)
+++ /trunk/doc/manual/en_US/user_Glossary.xml (revision 35277)
@@ -317,9 +317,9 @@
network connection over which data is transferred in both directions.
Typically graphics updates and audio are sent from the remote machine
- and keyboard and mouse input events are sent from the client.
- VirtualBox contains an enhanced implementation of the relevant
- standards implemented as a VirtualBox Remote Desktop Extension (VRDE),
- which is largely compatible with Microsoft's RDP implementation.
- See for details.
+ and keyboard and mouse input events are sent from the client. A
+ VirtualBox extension package by Oracle provides VRDP, an enhanced
+ implementation of the relevant standards which is largely compatible
+ with Microsoft's RDP implementation. See for
+ details.
@@ -430,7 +430,9 @@
- VirtualBox Remote Desktop Extension -- allows remot eaccess to
- virtual machines. VirtualBox provides a VRDE, which implements Remote
- Desktop Protocol (see RDP).
+ VirtualBox Remote Desktop Extension. This interface is built
+ into VirtualBox to allow VirtualBox extension packages to supply
+ remote access to virtual machines. A VirtualBox extension package by
+ Oracle provides VRDP support; see for
+ details.
Index: /trunk/doc/manual/en_US/user_VBoxManage.xml
===================================================================
--- /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35276)
+++ /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35277)
@@ -202,6 +202,6 @@
hostinfo displays information
- about the host system, such as CPUs, memory size and operating system
- version.
+ about the host system, such as CPUs, memory size and operating
+ system version.
@@ -845,5 +845,6 @@
- Serial port, audio, clipboard, remote desktop and USB settings
+ Serial port, audio, clipboard, remote desktop and USB
+ settings
The following other hardware settings are available through
@@ -950,7 +951,8 @@
--vrde on|off: With the
VirtualBox graphical user interface, this enables or disables the
- VirtualBox remote desktop extension (VRDE) server. Note that if you are using
- VBoxHeadless (see ), VRDE is enabled by default.
+ VirtualBox remote desktop extension (VRDE) server. Note that if
+ you are using VBoxHeadless (see
+ ), VRDE is enabled by
+ default.
@@ -972,6 +974,6 @@
--vrdeaddress <IP
address>: The IP address of the host network
- interface the VRDE server will bind to. If specified, the
- server will accept connections only on the specified host network
+ interface the VRDE server will bind to. If specified, the server
+ will accept connections only on the specified host network
interface.
@@ -986,7 +988,7 @@
--vrdemulticon on|off: This
- enables multiple connections to the same VRDE server, if the server
- supports this feature; see
- .
+ enables multiple connections to the same VRDE server, if the
+ server supports this feature; see .
@@ -994,21 +996,21 @@
--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
- connected to the server.
+ 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 connected to the
+ server.
--vrdevideochannel on|off:
- This enables video redirection, if it is supported by the VRDE server;
- see .
+ This enables video redirection, if it is supported by the VRDE
+ server; see .
--vrdevideochannelquality
- <percent>: Sets the image quality for
- video redirection; see : Sets the image quality for video
+ redirection; see .
@@ -1221,6 +1223,5 @@
- Starts a VM without a window for remote display
- only.
+ Starts a VM without a window for remote display only.
@@ -1722,6 +1723,7 @@
When "iscsi" is used with the
- --medium parameter, additional parameters
- must or can be used:
+ --medium parameter for iSCSI support --
+ see --, additional parameters must or can
+ be used:
server
@@ -1767,6 +1769,6 @@
(optional).
Currently, username and password are stored without
- encryption (i.e. in cleartext) in the machine configuration
- file.
+ encryption (i.e. in clear text) in the XML machine
+ configuration file.
@@ -1954,12 +1956,12 @@
sdelete tool provided by Microsoft.
Execute sdelete -c in the guest to
- zero the free disk space before compressing the virtual disk image.
-
-
+ zero the free disk space before compressing the virtual disk
+ image.
+
Please note that compacting is currently only available for
VDI images. A similar effect can be achieved by zeroing out free
blocks and then cloning the disk to any other dynamically expanding
- format. You can use this workaround until compacting is also supported
- for disk formats other than VDI.
+ format. You can use this workaround until compacting is also
+ supported for disk formats other than VDI.