user_Frontends.xml revision d2f75d9ba9861d2f77e46d06b818eff7dc680982
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title id="vrde">Remote display (VRDP support)</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox can display virtual machines remotely, meaning that a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine can execute on one machine even though the machine will be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync displayed on a second computer, and the machine will be controlled from
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync there as well, as if the virtual machine was running on that second
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync computer.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For maximum flexibility, starting with VirtualBox 4.0, VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync implements remote machine display through a generic extension interface,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the VirtualBox Remote Desktop Extension (VRDE). The base open-source
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox package only provides this interface, while implementations can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be supplied by third parties with VirtualBox extension packages, which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync must be installed separately from the base package. See <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="intro-installing" /> for more information.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Oracle provides support for the <emphasis role="bold">VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Remote Display Protocol (VRDP)</emphasis> in such a VirtualBox extension
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync package. When this package is installed, VirtualBox versions 4.0 and later
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync support VRDP the same way as binary (non-open-source) versions of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox before 4.0 did.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VRDP is a backwards-compatible extension to Microsoft's Remote
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Desktop Protocol (RDP). Typically graphics updates and audio are sent from
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the remote machine to the client, while keyboard and mouse events are sent
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync back. As a result, you can use any standard RDP client to control the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync remote VM.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Even when the extension is installed, the VRDP server is disabled by
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync default. It can easily be enabled on a per-VM basis either in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox Manager in the "Display" settings (see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="settings-display" />) or with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync further below), VRDP support will be automatically enabled since
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VBoxHeadless has no other means of output.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Since VRDP is backwards-compatible to RDP, you can use any
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync standard RDP viewer to connect to such a remote virtual machine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (examples follow below). For this to work, you must specify the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis role="bold">IP address</emphasis> of your
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis>host</emphasis> system (not of the virtual machine!) as the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server address to connect to, as well as the <emphasis role="bold">port
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync number</emphasis> that the RDP server is using.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>By default, VRDP uses TCP port
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>3389</computeroutput>. You will need to change the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync default port if you run more than one VRDP server, since the port can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync only be used by one server at a time; you might also need to change it
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync on Windows hosts since the default port might already be used by the RDP
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server that is built into Windows itself. Ports 5000 through 5050 are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync typically not used and might be a good choice.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The port can be changed either in the "Display" settings of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync graphical user interface or with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>--vrdeport</computeroutput> option of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specify a comma-separated list of ports or ranges of ports. Use a dash
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync between two port numbers to specify a range. The VRDP server will bind
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to <emphasis role="bold">one</emphasis> of available ports from the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync specified list. For example, <computeroutput>VBoxManage modifyvm "VM
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name" --vrdeport 5000,5010-5012</computeroutput> will configure the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="vboxmanage-modifyvm" /> for details.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The actual port used by a running VM can be either queried with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxManage showvminfo</computeroutput> command or seen
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync in the GUI on the "Runtime" tab of the "Session Information Dialog",
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync which is accessible via the "Machine" menu of the VM window.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Here follow examples for the most common RDP viewers:<itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On Windows, you can use the Microsoft Terminal Services
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Connector (<computeroutput>mstsc.exe</computeroutput>) that ships
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with Windows. You can start it by bringing up the "Run" dialog
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (press the Windows key and "R") and typing "mstsc". You can also
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync find it under "Start" -> "All Programs" -> "Accessories"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync -> "Remote Desktop Connection". If you use the "Run" dialog,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Replace "1.2.3.4" with the host IP address, and 3389 with a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync different port if necessary.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>When connecting to localhost in order to test the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync connection, the addresses
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>127.0.0.1</computeroutput> might not work using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>mstsc.exe</computeroutput>. Instead, the address
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>127.0.0.2[:3389]</computeroutput> has to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync used.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync <para>On other systems, you can use the standard open-source
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync <computeroutput>rdesktop</computeroutput> program. This ships with
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync most Linux distributions, but VirtualBox also comes with a
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync modified variant of rdesktop for remote USB support (see <xref
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync <para>With rdesktop, use a command line such as the
64863d3a0ffadf1ac248b295b78be5d55db6ee13vboxsync following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As said for the Microsoft viewer above, replace "1.2.3.4"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with the host IP address, and 3389 with a different port if
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync necessary. The <computeroutput>-a 16</computeroutput> option
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync requests a color depth of 16 bits per pixel, which we recommend.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (For best performance, after installation of the guest operating
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync system, you should set its display color depth to the same value).
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The <computeroutput>-N</computeroutput> option enables use of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync NumPad keys.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If you run the KDE desktop, you might prefer
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Again, replace "1.2.3.4" with the host IP address, and 3389
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with a different port if necessary. The "rdp:/" bit is required
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with krdc to switch it into RDP mode.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>With Sun Ray thin clients you can use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>uttsc</computeroutput>, which is part of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Sun Ray Windows Connector package. See the corresponding
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync documentation for details.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>VBoxHeadless, the remote desktop server</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>While any VM started from the VirtualBox Manager is capable of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync running virtual machines remotely, it is not convenient to have to run
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the full-fledged GUI if you never want to have VMs displayed locally in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the first place. In particular, if you are running server hardware whose
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync only purpose is to host VMs, and all your VMs are supposed to run
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync remotely over VRDP, then it is pointless to have a graphical user
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interface on the server at all -- especially since, on a Linux or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Solaris host, the VirtualBox manager comes with dependencies on the Qt
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and SDL libraries. This is inconvenient if you would rather not have the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync X Window system on your server at all.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox therefore comes with yet another front-end called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync output on the host at all, but instead only delivers VRDP data. This
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync front-end has no dependencies on the X Window system on Linux and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Solaris hosts.<footnote>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Before VirtualBox 1.6, the headless server was called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync compatibility, the VirtualBox installation still installs an
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync executable with that name as well.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To start a virtual machine with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput>, you have three
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync options:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>The
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync extra <computeroutput>--type</computeroutput> option causes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox to use <computeroutput>VBoxHeadless</computeroutput> as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the front-end to the internal virtualization engine instead of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Qt front-end.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>One alternative is to use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput> directly, as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync follows:<screen>VBoxHeadless --startvm <uuid|name></screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This way of starting the VM helps troubleshooting problems
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync reported by <computeroutput>VBoxManage startvm ...</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync because you can see sometimes more detailed error messages,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync especially for early failures before the VM execution is started.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync In normal situations <computeroutput>VBoxManage startvm</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is preferred since it runs the VM directly as a background process
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync which has to be done explicitly when directly starting
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput>.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The other alternative is to start
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput> from the VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Manager GUI, by holding the Shift key when starting a virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Note that when you use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync headless server has no other means of output, the VRDP server will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <emphasis>always</emphasis> be enabled, regardless of whether you had
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync enabled the VRDP server in the VM's settings. If this is undesirable
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (for example because you want to access the VM via
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>ssh</computeroutput> only), start the VM like
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this:<screen>VBoxHeadless --startvm <uuid|name> --vrde off</screen>To
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync have the VRDP server enabled depending on the VM configuration, as the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync other front-ends would, use this:<screen>VBoxHeadless --startvm <uuid|name> --vrde config</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync then the configuration settings of the VM are always used.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Step by step: creating a virtual machine on a headless
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The following instructions may give you an idea how to create a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine on a headless server over a network connection. We will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync create a virtual machine, establish an RDP connection and install a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest operating system -- all without having to touch the headless
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server. All you need is the following:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>VirtualBox on a server machine with a supported host
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync operating system. The VirtualBox extension pack for the VRDP
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync server must be installed (see the previous section). For the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following example, we will assume a Linux server.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>An ISO file accessible from the server, containing the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync installation data for the guest operating system to install (we
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will assume Windows XP in the following example).</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>A terminal connection to that host through which you can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync access a command line (e.g. via
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>An RDP viewer on the remote client; see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="rdp-viewers" /> above for examples.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </orderedlist>Note again that on the server machine, since we will
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync only use the headless server, neither Qt nor SDL nor the X Window system
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync will be needed.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On the headless server, create a new virtual machine:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Note that if you do not specify
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>--register</computeroutput>, you will have to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync manually use the <computeroutput>registervm</computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync command later.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Note further that you do not need to specify
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>--ostype</computeroutput>, but doing so selects
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync some sane default values for certain VM parameters, for example
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the RAM size and the type of the virtual network device. To get a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync complete list of supported operating systems you can use</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Make sure the settings for this VM are appropriate for the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Create a virtual hard disk for the VM (in this case, 10GB in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync size):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Set the VDI file created above as the first virtual hard
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Attach the ISO file that contains the operating system
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync installation that you want to install later to the virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If everything worked, you should see a copyright notice. If,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync instead, you are returned to the command line, then something went
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync wrong.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On the client machine, fire up the RDP viewer and try to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync connect to the server (see <xref linkend="rdp-viewers" /> above
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for how to use various common RDP viewers).</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>You should now be seeing the installation routine of your
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync guest operating system remotely in the RDP viewer.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As a special feature on top of the VRDP support, VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supports remote USB devices over the wire as well. That is, the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox guest that runs on one computer can access the USB devices of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the remote computer on which the VRDP data is being displayed the same
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync way as USB devices that are connected to the actual host. This allows
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync for running virtual machines on a VirtualBox host that acts as a server,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync where a client can connect from elsewhere that needs only a network
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync adapter and a display capable of running an RDP viewer. When USB devices
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync are plugged into the client, the remote VirtualBox server can access
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync them.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For these remote USB devices, the same filter rules apply as for
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync other USB devices, as described with <xref linkend="settings-usb" />.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync All you have to do is specify "Remote" (or "Any") when setting up these
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync rules.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Accessing remote USB devices is only possible if the RDP client
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supports this extension. On Linux and Solaris hosts, the VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync installation provides a suitable VRDP client called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>uttsc</computeroutput>, a client tailored for the use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with Sun Ray thin clients, also support accessing remote USB devices.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync RDP clients for other platforms will be provided in future VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync versions.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To make a remote USB device available to a VM,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>rdesktop-vrdp</computeroutput> should be started as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync devices only through <computeroutput>/proc/bus/usb</computeroutput>.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Please refer to <xref linkend="ts_usb-linux" /> for further details on how
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to properly set up the permissions. Furthermore it is advisable to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync disable automatic loading of any host driver on the remote host which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync might work on USB devices to ensure that the devices are accessible by
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the RDP client. If the setup was properly done on the remote host,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync plug/unplug events are visible on the VBox.log file of the VM.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For each virtual machine that is remotely accessible via RDP, you
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can individually determine if and how client connections are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authenticated. For this, use <computeroutput>VBoxManage
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync modifyvm</computeroutput> command with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>--vrdeauthtype</computeroutput> option; see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync linkend="vboxmanage-modifyvm" /> for a general introduction. Three
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync methods of authentication are available:<itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The "null" method means that there is no authentication at
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync all; any client can connect to the VRDP server and thus the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machine. This is, of course, very insecure and only to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync recommended for private networks.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The "external" method provides external authentication
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync through a special authentication library. VirtualBox ships with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync two such authentication libraries:<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The default authentication library,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxAuth</computeroutput>, authenticates
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync against user credentials of the hosts. Depending on the host
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync platform, this means:<itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On Linux hosts,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authenticates users against the host's PAM
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync system.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On Windows hosts,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authenticates users against the host's WinLogon
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync system.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On Mac OS X hosts,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authenticates users against the host's directory
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync service.<footnote>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Support for Mac OS X was added in version
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 3.2.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In other words, the "external" method per default
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync performs authentication with the user accounts that exist on
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the host system. Any user with valid authentication
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync credentials is accepted, i.e. the username does not have to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync correspond to the user running the VM.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>An additional library called
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxAuthSimple</computeroutput> performs
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication against credentials configured in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync "extradata" section of a virtual machine's XML settings
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync file. This is probably the simplest way to get
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication that does not depend on a running and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supported guest (see below). The following steps are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync required:<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Enable
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>VBoxAuthSimple</computeroutput> with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the following command:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To enable the library for a particular VM, you
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync must then switch authentication to external:<screen>VBoxManage modifyvm <vm> --vrdeauthtype external</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Replace
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><vm></computeroutput> with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VM name or UUID.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>You will then need to configure users and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync passwords by writing items into the machine's
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync extradata. Since the XML machine settings file, into
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync whose "extradata" section the password needs to be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync written, is a plain text file, VirtualBox uses hashes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to encrypt passwords. The following command must be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync used:<screen>VBoxManage setextradata <vm> "VBoxAuthSimple/users/<user>" <hash></screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Replace
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><vm></computeroutput> with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VM name or UUID,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><user></computeroutput> with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync user name who should be allowed to log in and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><hash></computeroutput> with the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync encrypted password. As an example, to obtain the hash
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync value for the password "secret", you can use the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This will print
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync You can then use VBoxManage setextradata to store this
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync value in the machine's "extradata" section.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As example, combined together, to set the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync password for the user "john" and the machine "My VM"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Finally, the "guest" authentication method performs
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication with a special component that comes with the Guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Additions; as a result, authentication is not performed on the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync accounts.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This method is currently still in testing and not yet
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync supported.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In addition to the methods described above, you can replace the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync default "external" authentication module with any other module. For
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this, VirtualBox provides a well-defined interface that allows you to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync write your own authentication module. This is described in detail in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox Software Development Kit (SDK) reference; please see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>RDP features data stream encryption, which is based on the RC4
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync symmetric cipher (with keys up to 128bit). The RC4 keys are being
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync replaced in regular intervals (every 4096 packets).</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>RDP provides different authentication methods:<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Historically, RDP4 authentication was used, with which the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync RDP client does not perform any checks in order to verify the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync identity of the server it connects to. Since user credentials can
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync be obtained using a "man in the middle" (MITM) attack, RDP4
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication is insecure and should generally not be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync used.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>RDP5.1 authentication employs a server certificate for which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the client possesses the public key. This way it is guaranteed
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that the server possess the corresponding private key. However, as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync this hard-coded private key became public some years ago, RDP5.1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync authentication is also insecure.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>RDP5.2 authentication uses the Enhanced RDP Security, which
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync means that an external security protocol is used to secure the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync connection. RDP4 and RDP5.1 use Standard RDP Security.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The VRDP server supports Enhanced RDP Security with TLS protocol and,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync as a part of TLS handshake, sends the server certificate to the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync client.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The <computeroutput>Security/Method</computeroutput> VRDE
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync property sets the desired security method, which is used for a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync connection. Valid values are:<itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync and Standard RDP Security connections are allowed. The security
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync method is negotiated with the client. This is the default setting.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>RDP</computeroutput> - only Standard RDP Security
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is accepted.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>TLS</computeroutput> - only Enhanced RDP Security
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is accepted. The client must support TLS.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </itemizedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync For example the following command allows a client to use either Standard
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync or Enhanced RDP Security connection:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>If the <computeroutput>Security/Method</computeroutput> property is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync set to either <computeroutput>Negotiate</computeroutput> or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>TLS</computeroutput>, the TLS protocol will be automatically
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync used by the server, if the client supports TLS. However, in order to use TLS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the server must possess the Server Certificate, the Server Private Key and the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Certificate Authority (CA) Certificate. The following example shows how to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync generate a server certificate.<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Create a CA self signed certificate:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>openssl req -new -x509 -days 365 -extensions v3_ca \
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync -keyout ca_key_private.pem -out ca_cert.pem</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Generate a server private key and a request for signing:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncopenssl req -new -key server_key_private.pem -out server_req.pem</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Generate the server certificate:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>openssl x509 -req -days 365 -in server_req.pem \
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The server must be configured to access the required files:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vboxmanage modifyvm "VM name" \
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vboxmanage modifyvm "VM name" \
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>vboxmanage modifyvm "VM name" \
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>As the client that connects to the server determines what type
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync of encryption will be used, with rdesktop, the Linux RDP viewer, use the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>-5</computeroutput> options.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <title>Multiple connections to the VRDP server</title>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The VRDP server of VirtualBox supports multiple simultaneous
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync connections to the same running VM from different clients. All connected
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync clients see the same screen output and share a mouse pointer and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync keyboard focus. This is similar to several people using the same
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync computer at the same time, taking turns at the keyboard.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To access two or more remote VM displays you have to enable the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VRDP multiconnection mode (see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The RDP client can select the virtual monitor number to connect to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync using the <computeroutput>domain</computeroutput> logon parameter
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync (<computeroutput>-d</computeroutput>). If the parameter ends with
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>@</computeroutput> followed by a number, VirtualBox
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync interprets this number as the screen index. The primary guest screen is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync selected with <computeroutput>@1</computeroutput>, the first secondary
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync screen is <computeroutput>@2</computeroutput>, etc.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The Microsoft RDP6 client does not let you specify a separate
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync domain name. Instead, use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>domain\username</computeroutput> in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>Username:</computeroutput> field -- for example,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput>name</computeroutput> must be supplied, and must be the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync name used to log in if the VRDP server is set up to require credentials.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync If it is not, you may use any text as the username.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync streams from the guest to the RDP client. Video frames are compressed
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync using the JPEG algorithm allowing a higher compression ratio than
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync standard RDP bitmap compression methods. It is possible to increase the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync compression ratio by lowering the video quality.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The VRDP server automatically detects video streams in a guest as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync frequently updated rectangular areas. As a result, this method works
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with any guest operating system without having to install additional
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync software in the guest; in particular, the Guest Additions are not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync required.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On the client side, however, currently only the Windows 7 Remote
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync Desktop Connection client supports this feature. If a client does not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync support video redirection, the VRDP server falls back to regular bitmap
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync updates.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The quality of the video is defined as a value from 10 to 100
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync percent, representing a JPEG compression level (where lower numbers mean
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync lower quality but higher compression). The quality can be changed using
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the following command: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>With VirtualBox 4.0 it is possible to disable display output,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync mouse and keyboard input, audio, remote USB or clipboard individually in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the VRDP server.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The following commands change corresponding server
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync settings:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage modifyvm "VM name" --vrdeproperty Client/DisableAudio=1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage modifyvm "VM name" --vrdeproperty Client/DisableClipboard=1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To reenable a feature use a similar command without the trailing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 1. For example: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>These properties were introduced with VirtualBox 3.2.10. However,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync in the 3.2.x series, it was necessary to use the following commands to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync alter these settings instead:</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableAudio" 1
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsyncVBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>To reenable a feature use a similar command without the trailing
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync 1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is, moving a virtual machine over a network from one VirtualBox host to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync another, while the virtual machine is running. This works regardless of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the host operating system that is running on the hosts: you can teleport
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync virtual machines between Solaris and Mac hosts, for example.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Teleporting requires that a machine be currently running on one
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync host, which is then called the <emphasis role="bold">"source"</emphasis>.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The host to which the virtual machine will be teleported will then be
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync called the <emphasis role="bold">"target"</emphasis>; the machine on the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync target is then configured to wait for the source to contact the target.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync The machine's running state will then be transferred from the source to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the target with minimal downtime.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Teleporting happens over any TCP/IP network; the source and the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync target only need to agree on a TCP/IP port which is specified in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync teleporting settings.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>At this time, there are a few prerequisites for this to work,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync however:<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On the target host, you must configure a virtual machine in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox with exactly the same hardware settings as the machine on
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the source that you want to teleport. This does not apply to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync settings which are merely descriptive, such as the VM name, but
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync obviously for teleporting to work, the target machine must have the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync same amount of memory and other hardware settings. Otherwise
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync teleporting will fail with an error message.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>The two virtual machines on the source and the target must
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync share the same storage (hard disks as well as floppy and CD/DVD
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync images). This means that they either use the same iSCSI targets or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that the storage resides somewhere on the network and both hosts
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>This also means that neither the source nor the target machine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync can have any snapshots.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Then perform the following steps:<orderedlist>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>On the <emphasis>target</emphasis> host, configure the virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync machine to wait for a teleport request to arrive when it is started,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync instead of actually attempting to start the machine. This is done
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync with the following VBoxManage command:<screen>VBoxManage modifyvm <targetvmname> --teleporter on --teleporterport <port></screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>where <computeroutput><targetvmname></computeroutput> is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the name of the virtual machine on the target host and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><port></computeroutput> is a TCP/IP port
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync number to be used on both the source and the target hosts. For
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync example, use 6000. For details, see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Start the VM on the target host. You will see that instead of
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync actually running, it will show a progress dialog. indicating that it
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is waiting for a teleport request to arrive.</para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>Start the machine on the <emphasis>source</emphasis> host as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync usual. When it is running and you want it to be teleported, issue
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the following command on the source host:<screen>VBoxManage controlvm <sourcevmname> teleport --host <targethost> --port <port></screen></para>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>where <computeroutput><sourcevmname></computeroutput> is
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync the name of the virtual machine on the source host (the machine that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync is currently running),
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <computeroutput><targethost></computeroutput> is the host or
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync IP name of the target host on which the machine is waiting for the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync teleport request, and <computeroutput><port></computeroutput>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync must be the same number as specified in the command on the target
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync host. For details, see <xref
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync </listitem>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>For testing, you can also teleport machines on the same host; in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync that case, use "localhost" as the hostname on both the source and the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync target host.<note>
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync <para>In rare cases, if the CPUs of the source and the target are very
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync different, teleporting can fail with an error message, or the target
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync may hang. This may happen especially if the VM is running application
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync software that is highly optimized to run on a particular CPU without
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync correctly checking that certain CPU features are actually present.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync VirtualBox filters what CPU capabilities are presented to the guest
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync operating system. Advanced users can attempt to restrict these virtual
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync CPU capabilities with the <computeroutput>VBoxManage --modifyvm