source: vbox/trunk/doc/manual/en_US/user_Frontends.xml@ 35173

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter>
  <title>Remote virtual machines</title>

  <sect1>
    <title id="vrdp">Remote display (VRDP support)</title>

    <para>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.</para>

    <para>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 <xref
    linkend="intro-installing" /> for more information. </para>

    <para>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.</para>

    <para>VRDP is a backwards-compatible extension to Microsoft's Remote
    Desktop Protocol (RDP). Typically graphics updates and audio are sent from
    the remote machine to the client, while keyboard and mouse events are sent
    back. As a result, you can use any standard RDP client to control the
    remote VM.</para>

    <para>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 <xref
    linkend="settings-display" />) or with
    <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para>

    <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
    further below), VRDP support will be automatically enabled since
    VBoxHeadless has no other means of output.</para>

    <sect2 id="rdp-viewers">
      <title>Common third-party RDP viewers</title>

      <para>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
      <emphasis role="bold">IP address</emphasis> of your
      <emphasis>host</emphasis> system (not of the virtual machine!) as the
      server address to connect to, as well as the <emphasis role="bold">port
      number</emphasis> that the RDP server is using.</para>

      <para>By default, VRDP uses TCP port
      <computeroutput>3389</computeroutput>. 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.</para>

      <para>The port can be changed either in the "Display" settings of the
      graphical user interface or with
      <computeroutput>--vrdpport</computeroutput> option of the
      <computeroutput>VBoxManage modifyvm</computeroutput> 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 <emphasis role="bold">one</emphasis> of available ports from the
      specified list. For example, <computeroutput>VBoxManage modifyvm "VM
      name" --vrdeport 5000,5010-5012</computeroutput> will configure the
      server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
      linkend="vboxmanage-modifyvm" /> for details.</para>

      <para>The actual port used by a running VM can be either queried with
      <computeroutput>VBoxManage showvminfo</computeroutput> 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.</para>

      <para>Here follow examples for the most common RDP viewers:<itemizedlist>
          <listitem>
            <para>On Windows, you can use the Microsoft Terminal Services
            Connector (<computeroutput>mstsc.exe</computeroutput>) 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" -&gt; "All Programs" -&gt; "Accessories"
            -&gt; "Remote Desktop Connection". If you use the "Run" dialog,
            you can type in options directly:<screen>mstsc 1.2.3.4[:3389]</screen></para>

            <para>Replace "1.2.3.4" with the host IP address, and 3389 with a
            different port if necessary.</para>

            <note>
              <para>When connecting to localhost in order to test the
              connection, the addresses
              <computeroutput>localhost</computeroutput> and
              <computeroutput>127.0.0.1</computeroutput> might not work using
              <computeroutput>mstsc.exe</computeroutput>. Instead, the address
              <computeroutput>127.0.0.2[:3389]</computeroutput> has to be
              used.</para>
            </note>
          </listitem>

          <listitem>
            <para>On other systems, you can use the standard open-source
            <computeroutput>rdesktop</computeroutput> program. This ships with
            most Linux distributions, but VirtualBox also comes with a
            modified variant of rdesktop for remote USB support (see <xref
            linkend="usb-over-rdp" /> below).</para>

            <para>With rdesktop, use a command line such as the
            following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>

            <para>As said for the Microsoft viewer above, replace "1.2.3.4"
            with the host IP address, and 3389 with a different port if
            necessary. The <computeroutput>-a 16</computeroutput> 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).
            The <computeroutput>-N</computeroutput> option enables use of the
            NumPad keys.</para>
          </listitem>

          <listitem>
            <para>If you run the KDE desktop, you might prefer
            <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
            command line would look like this:<screen>krdc --window --high-quality rdp:/1.2.3.4[:3389]</screen></para>

            <para>Again, replace "1.2.3.4" with the host IP address, and 3389
            with a different port if necessary. The "rdp:/" bit is required
            with krdc to switch it into RDP mode.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="vboxheadless">
      <title>VBoxHeadless, the VRDP-only server</title>

      <para>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 servers whose only
      purpose is to host VMs, and all your VMs are supposed to run remotely
      over VRDP, then it is pointless to have a graphical user interface on
      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.</para>

      <para>VirtualBox therefore comes with yet another front-end called
      <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
      output on the host at all, but instead only delivers VRDP data.<footnote>
          <para>Before VirtualBox 1.6, the headless server was called
          <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
          compatibility, the VirtualBox installation still installs an
          executable with that name as well.</para>
        </footnote></para>

      <para>To start a virtual machine with VBoxHeadless, you have two
      options:</para>

      <itemizedlist>
        <listitem>
          <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>
          The extra <computeroutput>--type</computeroutput> option causes the
          VirtualBox core to use <computeroutput>VBoxHeadless</computeroutput>
          as the front-end to the internal virtualization engine.</para>
        </listitem>

        <listitem>
          <para>The alternative is to use
          <computeroutput>VBoxHeadless</computeroutput> directly, as
          follows:<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>

          <para>This way of starting the VM has the advantage that you can see
          more detailed error messages, especially for early failures before
          the VM execution is started. If you have trouble with
          <computeroutput>VBoxManage startvm</computeroutput>, it can help
          greatly to start <computeroutput>VBoxHeadless</computeroutput>
          directly to diagnose the problem cause.</para>
        </listitem>
      </itemizedlist>

      <para>Note that when you use
      <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
      headless server has no other means of output, the built-in RDP server
      will <emphasis>always</emphasis> be enabled, regardless of whether you
      have enabled the VRDP server in the VM's settings. If this is
      undesirable (for example because you want to access the VM via
      <computeroutput>ssh</computeroutput> only), start the VM like
      this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=off</screen>To
      have the VRDP server use the setting from the VM configuration, as the
      other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=config</screen></para>
    </sect2>

    <sect2>
      <title>Step by step: creating a virtual machine on a headless
      server</title>

      <para>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:</para>

      <para><orderedlist>
          <listitem>
            <para>VirtualBox on a server machine with a supported host
            operating system; for the following example, we will assume a
            Linux server;</para>
          </listitem>

          <listitem>
            <para>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);</para>
          </listitem>

          <listitem>
            <para>a terminal connection to that host over which you can access
            a command line (e.g. via <computeroutput>telnet</computeroutput>
            or <computeroutput>ssh</computeroutput>);</para>
          </listitem>

          <listitem>
            <para>an RDP viewer on the remote client; see <xref
            linkend="rdp-viewers" /> above for examples.</para>
          </listitem>
        </orderedlist>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.</para>

      <para><orderedlist>
          <listitem>
            <para>On the headless server, create a new virtual machine:</para>

            <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>

            <para>Note that if you do not specify
            <computeroutput>--register</computeroutput>, you will have to
            manually use the registervm command later.</para>

            <para>Note further that you do not need to specify
            <computeroutput>--ostype</computeroutput> 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</para>

            <screen>VBoxManage list ostypes</screen>
          </listitem>

          <listitem>
            <para>Make sure the settings for this VM are appropriate for the
            guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
          </listitem>

          <listitem>
            <para>Create a virtual hard disk for the VM (in this case, 10GB in
            size) and register it with VirtualBox:<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000 --remember</screen></para>
          </listitem>

          <listitem>
            <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
      --add ide --controller PIIX4</screen></para>
          </listitem>

          <listitem>
            <para>Set this newly created VDI file as the first virtual hard
            disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
      --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
          </listitem>

          <listitem>
            <para>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:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
      --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
          </listitem>

          <listitem>
            <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>

            <para>If everything worked, you should see a copyright notice. If,
            instead, you are returned to the command line, then something went
            wrong.</para>
          </listitem>

          <listitem>
            <para>On the client machine, fire up the RDP viewer and try to
            connect to the server (see <xref linkend="rdp-viewers" /> above
            for how to use various common RDP viewers).</para>

            <para>You should now be seeing the installation routine of your
            guest operating system in the RDP viewer.</para>
          </listitem>
        </orderedlist></para>
    </sect2>

    <sect2 id="usb-over-rdp">
      <title>Remote USB</title>

      <para>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.</para>

      <para>For these remote USB devices, the same filter rules apply as for
      other USB devices, as described with <xref linkend="settings-usb" />.
      All you have to do is specify "Remote" (or "Any") when setting up these
      rules.</para>

      <para>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
      <computeroutput>rdesktop-vrdp</computeroutput>. RDP clients for other
      platforms will be provided in future VirtualBox versions.</para>

      <para>To make a remote USB device available to a VM,
      <computeroutput>rdesktop-vrdp</computeroutput> should be started as
      follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>Note
      that <computeroutput>rdesktop-vrdp</computeroutput> can access USB
      devices only through <computeroutput>/proc/bus/usb</computeroutput>.
      Please refer to <xref linkend="usb_linux" /> for further details on how
      to properly set up the permissions. 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.</para>
    </sect2>

    <sect2 id="vbox-auth">
      <title>RDP authentication</title>

      <para>For each virtual machine that is remotely accessible via RDP, you
      can individually determine if and how RDP connections are
      authenticated.</para>

      <para>For this, use <computeroutput>VBoxManage modifyvm</computeroutput>
      command with the <computeroutput>--vrdeauthtype</computeroutput> option;
      see <xref linkend="vboxmanage-modifyvm" /> for a general introduction.
      Three methods of authentication are available:<itemizedlist>
          <listitem>
            <para>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.</para>
          </listitem>

          <listitem>
            <para>The "external" method provides external authentication
            through a special authentication library.</para>

            <para>VirtualBox comes with three default libraries for external
            authentication:<itemizedlist>
                <listitem>
                  <para>On Linux hosts,
                  <computeroutput>VBoxAuth.so</computeroutput> authenticates
                  users against the host's PAM system.</para>
                </listitem>

                <listitem>
                  <para>On Windows hosts,
                  <computeroutput>VBoxAuth.dll</computeroutput> authenticates
                  users against the host's WinLogon system.</para>
                </listitem>

                <listitem>
                  <para>On Mac OS X hosts,
                  <computeroutput>VBoxAuth.dylib</computeroutput>
                  authenticates users against the host's directory
                  service.<footnote>
                      <para>Support for Mac OS X was added in version
                      3.2.</para>
                    </footnote></para>
                </listitem>
              </itemizedlist></para>

            <para>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.</para>
          </listitem>

          <listitem>
            <para>An additional library called
            <computeroutput>VBoxAuthSimple</computeroutput> 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
            <computeroutput>VBoxManage setproperty vrdeauthlibrary
            "VBoxAuthSimple"</computeroutput>. To enable the library for a VM,
            switch authentication to external using <computeroutput>VBoxManage
            modifyvm "VM name" --vrdeauthtype external</computeroutput>. Last
            but not least, you have to configure users and passwords. Here is
            an example for the user "john" with the password "secret":
            <computeroutput>VBoxManage internalcommands passwordhash
            "secret"</computeroutput> This will give you the hash value
            "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
            which you set using <computeroutput>VBoxManage setextradata "VM
            name" "VBoxAuthSimple/users/john"
            "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"</computeroutput>.</para>
          </listitem>

          <listitem>
            <para>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.</para>
          </listitem>
        </itemizedlist></para>

      <para>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; see <xref
      linkend="vbox-authenticate-sdk" /> for details.</para>
    </sect2>

    <sect2 id="vrdp-crypt">
      <title>RDP encryption</title>

      <para>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).</para>

      <para>RDP provides three different authentication methods:<orderedlist>
          <listitem>
            <para>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.</para>
          </listitem>

          <listitem>
            <para>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 and cannot be recommended.</para>
          </listitem>

          <listitem>
            <para>RDP5.2 authentication is based on TLS 1.0 with
            customer-supplied certificates. The server supplies a certificate
            to the client which must be signed by a certificate authority (CA)
            that the client trusts (for the Microsoft RDP Client 5.2, the CA
            has to be added to the Windows Trusted Root Certificate
            Authorities database). VirtualBox allows you to supply your own CA
            and server certificate and uses OpenSSL for encryption.</para>
          </listitem>
        </orderedlist></para>

      <para>While VirtualBox supports all of the above, only RDP5.2
      authentication should be used in environments where security is a
      concern. As the client that connects to the server determines what type
      of encryption will be used, with rdesktop, the Linux RDP viewer, use the
      <computeroutput>-4</computeroutput> or
      <computeroutput>-5</computeroutput> options.</para>
    </sect2>

    <sect2 id="vrdp-multiconnection">
      <title>Multiple VRDP connections</title>

      <para>The built-in RDP server of VirtualBox supports simultaneous
      connections to the same running VM from different clients. All connected
      clients see the same screen output and share a mouse pointer and
      keyboard focus. This is similar to several people using the same
      computer at the same time, taking turns at the keyboard.</para>

      <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
    </sect2>

    <sect2 id="vrdp-multimonitor">
      <title>Multiple remote monitors</title>

      <para>To access two or more remote VM displays you have to enable the
      RDP multiconnection mode (see <xref
      linkend="vrdp-multiconnection" />).</para>

      <para>The RDP client can select the virtual monitor number to connect to
      using the <computeroutput>domain</computeroutput> logon parameter
      (<computeroutput>-d</computeroutput>). If the parameter ends with
      <computeroutput>@</computeroutput> followed by a number, the VirtualBox
      RDP server interprets this number as the screen index. The primary guest
      screen is selected with <computeroutput>@1</computeroutput>, the first
      secondary screen is <computeroutput>@2</computeroutput>, etc.</para>

      <para>The MS RDP6 client does not let you specify a separate domain
      name. Instead, use <computeroutput>domain\username</computeroutput> in
      the <computeroutput>Username:</computeroutput> field -- for example,
      <computeroutput>@2\name</computeroutput>.
      <computeroutput>name</computeroutput> 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.</para>
    </sect2>

    <sect2 id="vrdp-videochannel">
      <title>VRDP video redirection</title>

      <para>Starting with VirtualBox 3.2, the RDP 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.</para>

      <para>Video streams in a guest are detected by the RDP 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.</para>

      <para>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
      updates.</para>

      <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>

      <para>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: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannelquality 75</screen></para>
    </sect2>

    <sect2 id="vrdp-customization">
      <title>VRDP customization</title>

      <para>Starting with VirtualBox 3.2.10, it is possible to disable display
      output, mouse and keyboard input, audio, remote USB or clipboard in the
      VRDP server.</para>

      <para>The following commands change corresponding server
      settings:</para>

      <screen>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</screen>

      <para>To reenable a feature use a similar command without the trailing
      1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
    </sect2>
  </sect1>

  <sect1 id="teleporting">
    <title>Teleporting</title>

    <para>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.</para>

    <para>Teleporting requires that a machine be currently running on one
    host, which is then called the <emphasis role="bold">"source"</emphasis>.
    The host to which the virtual machine will be teleported will then be
    called the <emphasis role="bold">"target"</emphasis>; 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.</para>

    <para>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.</para>

    <para>At this time, there are a few prerequisites for this to work,
    however:<orderedlist>
        <listitem>
          <para>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.</para>
        </listitem>

        <listitem>
          <para>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.</para>

          <para>This also means that neither the source nor the target machine
          can have any snapshots.</para>
        </listitem>
      </orderedlist></para>

    <para>Then perform the following steps:<orderedlist>
        <listitem>
          <para>On the <emphasis>target</emphasis> 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:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>

          <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
          the name of the virtual machine on the target host and
          <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
          number to be used on both the source and the target hosts. For
          example, use 6000. For details, see <xref
          linkend="vboxmanage-modifyvm-teleport" />.</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>

        <listitem>
          <para>Start the machine on the <emphasis>source</emphasis> host as
          usual. When it is running and you want it to be teleported, issue
          the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>

          <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
          the name of the virtual machine on the source host (the machine that
          is currently running),
          <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
          IP name of the target host on which the machine is waiting for the
          teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
          must be the same number as specified in the command on the target
          host. For details, see <xref
          linkend="vboxmanage-controlvm" />.</para>
        </listitem>
      </orderedlist></para>

    <para>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.<note>
        <para>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 <computeroutput>VBoxManage --modifyvm
        --cpuid</computeroutput> command; see <xref
        linkend="vboxmanage-modifyvm-teleport" />.</para>
      </note></para>
  </sect1>
</chapter>