Table of Contents
VirtualBox can display virtual machines remotely, meaning that a virtual machine can execute on one computer 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 implements remote machine display through a generic extension interface, the VirtualBox Remote Desktop Extension (VRDE). The base open-source VirtualBox package only provides this interface, while implementations can be supplied by third parties with VirtualBox extension packages, which must be installed separately from the base package. See Section 1.5, “Installing VirtualBox and extension packs” 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 Desktop Protocol (RDP). As a result, you can use any standard RDP client to control the remote VM.
Even when the extension is installed, the VRDP server is disabled by
default. It can easily be enabled on a per-VM basis either in the
VirtualBox Manager in the "Display" settings (see Section 3.5, “Display settings”) or with
VBoxManage modifyvm "VM name" --vrde on
If you use
further below), VRDP support will be automatically enabled since
VBoxHeadless has no other means of output.
By default, the VRDP server uses TCP port
3389. You will need to change the
default port if you run more than one VRDP server, since the port can
only be used by one server at a time; you might also need to change it
on Windows hosts since the default port might already be used by the RDP
server that is built into Windows itself. Ports 5000 through 5050 are
typically not used and might be a good choice.
The port can be changed either in the "Display" settings of the
graphical user interface or with
--vrdeport option of the
VBoxManage modifyvm command. 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. For example,
VBoxManage modifyvm "VM
name" --vrdeport 5000,5010-5012 will configure the
server to bind to one of the ports 5000, 5010, 5011 or 5012. See Section 8.8.4, “Remote machine settings” for details.
The actual port used by a running VM can be either queried with
VBoxManage showvminfo command or seen
in the GUI on the "Runtime" tab of the "Session Information Dialog",
which is accessible via the "Machine" menu of the VM window.
Support for IPv6 has been implemented in VirtualBox 4.3. If the host OS supports IPv6 the VRDP server will automatically listen for IPv6 connections in addition to IPv4.
Since VRDP is backwards-compatible to RDP, you can use any standard RDP viewer to connect to such a remote virtual machine (examples follow below). For this to work, you must specify the IP address of your host system (not of the virtual machine!) as the server address to connect to, as well as the port number that the VRDP server is using.
Here follow examples for the most common RDP viewers:
On Windows, you can use the Microsoft Terminal Services
mstsc.exe) that ships
with Windows. You can start it by bringing up the "Run" dialog
(press the Windows key and "R") and typing "mstsc". You can also
find it under "Start" -> "All Programs" -> "Accessories"
-> "Remote Desktop Connection". If you use the "Run" dialog,
you can type in options directly:
18.104.22.168 with the host IP address,
3389 with a different port if necessary.
IPv6 address must be enclosed in square brackets to specify a port.
When connecting to localhost in order to test the
connection, the addresses
127.0.0.1 might not work using
mstsc.exe. Instead, the address
127.0.0.2[:3389] has to be
On other systems, you can use the standard open-source
rdesktop program. This ships with
most Linux distributions, but VirtualBox also comes with a
modified variant of rdesktop for remote USB support (see Section 7.1.4, “Remote USB” below).
With rdesktop, use a command line such as the following:
rdesktop -a 16 -N 22.214.171.124:3389
As said for the Microsoft viewer above, replace
with the host IP address, and
3389 with a different port if
-a 16 option
requests a color depth of 16 bits per pixel, which we recommend.
(For best performance, after installation of the guest operating
system, you should set its display color depth to the same value).
-N option enables use of the
If you run the KDE desktop, you might prefer
krdc, the KDE RDP viewer. The
command line would look like this:
126.96.36.199 with the host IP address,
3389 with a different port if necessary.
The "rdp://" bit is required with krdc to switch it into RDP mode.
With Sun Ray thin clients you can use
uttsc, which is part of the
Sun Ray Windows Connector package. See the corresponding
documentation for details.
While any VM started from the VirtualBox Manager is capable of 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 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 VRDP data. This
front-end has no dependencies on the X Window system on Linux and
To start a virtual machine with
VBoxHeadless, you have three
You can use
VBoxManage startvm "VM name" --type headless
--type option causes
VirtualBox to use
the front-end to the internal virtualization engine instead of the
One alternative is to use
VBoxHeadless directly, as
VBoxHeadless --startvm <uuid|name>
This way of starting the VM helps troubleshooting problems
VBoxManage startvm ...
because you can see sometimes more detailed error messages,
especially for early failures before the VM execution is started.
In normal situations
is preferred since it runs the VM directly as a background process
which has to be done explicitly when directly starting
The other alternative is to start
VBoxHeadless from the VirtualBox
Manager GUI, by holding the Shift key when starting a virtual
Note that when you use
VBoxHeadless to start a VM, since the
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
VBoxHeadless --startvm <uuid|name> --vrde off
To have the VRDP server enabled depending on the VM configuration, as the other front-ends would, use this:
VBoxHeadless --startvm <uuid|name> --vrde config
If you start the VM with
VBoxManage startvm ...
then the configuration settings of the VM are always used.
The following instructions may give you an idea how to create a virtual machine on a headless server over a network connection. We will 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:
VirtualBox on a server machine with a supported host operating system. The VirtualBox extension pack for the VRDP server must be installed (see the previous section). For the following example, we will assume a Linux server.
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
An RDP viewer on the remote client; see Section 7.1.1, “Common third-party RDP viewers” above for examples.
Note again that on the server machine, since we will only use the headless server, neither Qt nor SDL nor the X Window system will be needed.
On the headless server, create a new virtual machine:
VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register
Note that if you do not specify
--register, you will have to
manually use the
Note further that you do not need to specify
--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
complete list of supported operating systems you can use
VBoxManage list ostypes
Make sure the settings for this VM are appropriate for the guest operating system that we will install. For example:
VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat
Create a virtual hard disk for the VM (in this case, 10GB in size):
VBoxManage createhd --filename "WinXP.vdi" --size 10000
Add an IDE Controller to the new VM:
VBoxManage storagectl "Windows XP" --name "IDE Controller" --add ide --controller PIIX4
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"
Attach the ISO file that contains the operating system installation that you want to install later to the virtual machine, so the machine can boot from it:
VBoxManage storageattach "Windows XP" --storagectl "IDE Controller" --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso
Start the virtual machine using VBoxHeadless:
VBoxHeadless --startvm "Windows XP"
If everything worked, you should see a copyright notice. If, instead, you are returned to the command line, then something went wrong.
On the client machine, fire up the RDP viewer and try to connect to the server (see Section 7.1.1, “Common third-party RDP viewers” above for how to use various common RDP viewers).
You should now be seeing the installation routine of your guest operating system remotely in the RDP viewer.
As a special feature on top of the VRDP support, VirtualBox supports remote USB devices over the wire as well. That is, the VirtualBox guest that runs on one computer can access the USB devices of the remote computer on which the VRDP data is being displayed the same way as USB devices that are connected to the actual host. This allows for running virtual machines on a VirtualBox host that acts as a server, where a client can connect from elsewhere that needs only a network adapter and a display capable of running an RDP viewer. When USB devices are plugged into the client, the remote VirtualBox server can access them.
For these remote USB devices, the same filter rules apply as for other USB devices, as described with Section 3.10.1, “USB settings”. All you have to do is specify "Remote" (or "Any") when setting up these rules.
Accessing remote USB devices is only possible if the RDP client
supports this extension. On Linux and Solaris hosts, the VirtualBox
installation provides a suitable VRDP client called
rdesktop-vrdp. Recent versions of
uttsc, a client tailored for the use
with Sun Ray thin clients, also support accessing remote USB devices.
RDP clients for other platforms will be provided in future VirtualBox
To make a remote USB device available to a VM,
rdesktop-vrdp should be started as
rdesktop-vrdp -r usb -a 16 -N my.host.address
Please refer to Section 12.7.7, “USB not working” for further details on how to properly set up the permissions for USB devices. Furthermore it is advisable to disable automatic loading of any host driver on the remote host which might work on USB devices to ensure that the devices are accessible by the RDP client. If the setup was properly done on the remote host, plug/unplug events are visible on the VBox.log file of the VM.
For each virtual machine that is remotely accessible via RDP, you
can individually determine if and how client connections are
authenticated. For this, use
modifyvm command with the
--vrdeauthtype option; see Section 8.8, “VBoxManage modifyvm” 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 VRDP server and thus the virtual machine. This is, of course, very insecure and only to be recommended for private networks.
The "external" method provides external authentication through a special authentication library. VirtualBox ships with two such authentication libraries:
The default authentication library,
against user credentials of the hosts. Depending on the host
platform, this means:
On Linux hosts,
authenticates users against the host's PAM
On Windows hosts,
authenticates users against the host's WinLogon
On Mac OS X hosts,
authenticates users against the host's directory
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
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
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 name" --vrdeauthtype external
<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 name" "VBoxAuthSimple/users/<user>" <hash>
<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
VBoxManage internalcommands passwordhash "secret"
This will print
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
Finally, the "guest" authentication method performs authentication with a special component that comes with the Guest 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 VirtualBox Software Development Kit (SDK) reference; please see Chapter 11, VirtualBox programming interfaces for details.
RDP features data stream encryption, which is based on the RC4 symmetric cipher (with keys up to 128bit). The RC4 keys are being replaced in regular intervals (every 4096 packets).
RDP provides different authentication methods:
Historically, RDP4 authentication was used, with which the 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 authentication is insecure and should generally not be used.
RDP5.1 authentication employs a server certificate for which the client possesses the public key. This way it is guaranteed that the server possess the corresponding private key. However, as this hard-coded private key became public some years ago, RDP5.1 authentication is also insecure.
RDP5.2 authentication uses the Enhanced RDP Security, which means that an external security protocol is used to secure the connection. RDP4 and RDP5.1 use Standard RDP Security. The VRDP server supports Enhanced RDP Security with TLS protocol and, as a part of TLS handshake, sends the server certificate to the client.
property sets the desired security method, which is used for a
connection. Valid values are:
Negotiate - both Enhanced (TLS)
and Standard RDP Security connections are allowed. The security
method is negotiated with the client. This is the default setting.
RDP - only Standard RDP Security
TLS - only Enhanced RDP Security
is accepted. The client must support TLS.
For example the following command allows a client to use either Standard or Enhanced RDP Security connection:
vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"
Security/Method property is
set to either
TLS, the TLS protocol will be automatically
used by the server, if the client supports TLS. However, in order to use TLS
the server must possess the Server Certificate, the Server Private Key and the
Certificate Authority (CA) Certificate. The following example shows how to
generate a server certificate.
openssl req -new -x509 -days 365 -extensions v3_ca \ -keyout ca_key_private.pem -out ca_cert.pem
openssl genrsa -out server_key_private.pem openssl req -new -key server_key_private.pem -out server_req.pem
openssl x509 -req -days 365 -in server_req.pem \ -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem
The server must be configured to access the required files:
vboxmanage modifyvm "VM name" \ --vrdeproperty "Security/CACertificate=path/ca_cert.pem"
vboxmanage modifyvm "VM name" \ --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"
vboxmanage modifyvm "VM name" \ --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"
As the client that connects to the server determines what type
of encryption will be used, with rdesktop, the Linux RDP viewer, use the
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 keyboard focus. This is similar to several people using the same computer at the same time, taking turns at the keyboard.
The following command enables multiple connection mode:
VBoxManage modifyvm "VM name" --vrdemulticon on
To access two or more remote VM displays you have to enable the VRDP multiconnection mode (see Section 7.1.7, “Multiple connections to the VRDP server”).
The RDP client can select the virtual monitor number to connect to
domain logon parameter
-d). If the parameter ends with
@ followed by a number, VirtualBox
interprets this number as the screen index. The primary guest screen is
@1, the first secondary
The Microsoft RDP6 client does not let you specify a separate
domain name. Instead, use
domain\username in the
Username: field -- for example,
name must be supplied, and must be the
name used to log in if the VRDP server is set up to require credentials.
If it is not, you may use any text as the username.
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 standard RDP bitmap compression methods. It is possible to increase the compression ratio by lowering the video quality.
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 falls back to regular bitmap updates.
The following command enables video redirection:
VBoxManage modifyvm "VM name" --vrdevideochannel on
The quality of the video is defined as a value from 10 to 100 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
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 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=
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 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1
To reenable a feature use a similar command without the trailing 1. For example:
VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"
Starting with version 3.1, VirtualBox supports "teleporting" -- that is, moving a virtual machine over a network from one VirtualBox host to another, while the virtual machine is running. This works regardless of the host operating system that is running on the hosts: you can teleport virtual machines between Solaris and Mac hosts, for example.
Teleporting requires that a machine be currently running on one host, which is then called the "source". The host to which the virtual machine will be teleported will then be called the "target"; the machine on the target is then configured to wait for the source to contact the target. The machine's running state will then be transferred from the source to the target with minimal downtime.
Teleporting happens over any TCP/IP network; the source and the target only need to agree on a TCP/IP port which is specified in the teleporting settings.
At this time, there are a few prerequisites for this to work, however:
On the target host, you must configure a virtual machine in VirtualBox with exactly the same hardware settings as the machine on the source that you want to teleport. This does not apply to settings which are merely descriptive, such as the VM name, but obviously for teleporting to work, the target machine must have the same amount of memory and other hardware settings. Otherwise teleporting will fail with an error message.
The two virtual machines on the source and the target must share the same storage (hard disks as well as floppy and CD/DVD images). This means that they either use the same iSCSI targets or that the storage resides somewhere on the network and both hosts have access to it via NFS or SMB/CIFS.
This also means that neither the source nor the target machine can have any snapshots.
Then perform the following steps:
On the target host, configure the virtual machine to wait for a teleport request to arrive when it is started, instead of actually attempting to start the machine. This is done with the following VBoxManage command:
VBoxManage modifyvm <targetvmname> --teleporter on --teleporterport <port>
the name of the virtual machine on the target host and
<port> is a TCP/IP port
number to be used on both the source and the target hosts. For
example, use 6000. For details, see Section 8.8.5, “Teleporting settings”.
Start the VM on the target host. You will see that instead of actually running, it will show a progress dialog. indicating that it is waiting for a teleport request to arrive.
Start the machine on the source host as usual. When it is running and you want it to be teleported, issue the following command on the source host:
VBoxManage controlvm <sourcevmname> teleport --host <targethost> --port <port>
the name of the virtual machine on the source host (the machine that
is currently running),
<targethost> is the host or
IP name of the target host on which the machine is waiting for the
teleport request, and
must be the same number as specified in the command on the target
host. For details, see Section 8.13, “VBoxManage controlvm”.
For testing, you can also teleport machines on the same host; in that case, use "localhost" as the hostname on both the source and the target host.
In rare cases, if the CPUs of the source and the target are very
different, teleporting can fail with an error message, or the target
may hang. This may happen especially if the VM is running application
software that is highly optimized to run on a particular CPU without
correctly checking that certain CPU features are actually present.
VirtualBox filters what CPU capabilities are presented to the guest
operating system. Advanced users can attempt to restrict these virtual
CPU capabilities with the
--cpuid command; see Section 8.8.5, “Teleporting settings”.