VirtualBox

Ignore:
Timestamp:
Dec 3, 2010 9:44:32 AM (14 years ago)
Author:
vboxsync
Message:

Manual: extension packs, VRDE

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/en_US/user_Frontends.xml

    r34563 r34680  
    11<?xml version="1.0" encoding="UTF-8"?>
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
    3   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
     3"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
    44<chapter>
    55  <title>Remote virtual machines</title>
    66
    77  <sect1>
    8     <title id="vrdp">Remote display (VRDP support)</title>
     8    <title id="vrdp">The VirtualBox Remote Desktop Extension (VRDE)</title>
    99
    1010    <para>VirtualBox, the graphical user interface, has a built-in server for
    11     the VirtualBox Remote Desktop Protocol (VRDP). This allows you to see the
     11    the Microsoft Remote Desktop Protocol (RDP). This allows you to see the
    1212    output of a virtual machine's window remotely on any other computer and
    1313    control the virtual machine from there, as if the virtual machine was
    14     running locally.</para>
    15 
    16     <para>VRDP is a backwards-compatible extension to Microsoft's Remote
    17     Desktop Protocol (RDP). Typically graphics updates and audio are sent from
    18     the remote machine to the client, while keyboard and mouse events are sent
    19     back. As a result, you can use any standard RDP client to control the
    20     remote VM.</para>
    21 
    22     <para>With <computeroutput>VirtualBox</computeroutput>, the graphical user
    23     interface, the VRDP server is disabled by default, but can easily be
    24     enabled on a per-VM basis either in the "Display" settings (see <xref
    25     linkend="settings-display" />) or with
    26     <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrdp on</screen></para>
     14    running locally.<note>
     15        <para>The VRDE is shipped as a VirtualBox extension package, which
     16        must be installed separately. See <xref linkend="intro-installing" />
     17        for more installation.</para>
     18      </note></para>
     19
     20    <para>The VirtualBox Remote Desktop Extension (VRDE) is a
     21    backwards-compatible extension to Microsoft's Remote Desktop Protocol
     22    (RDP). Typically graphics updates and audio are sent from the remote
     23    machine to the client, while keyboard and mouse events are sent back. As a
     24    result, you can use any standard RDP client to control the remote
     25    VM.</para>
     26
     27    <para>The RDP server is disabled by default. If the VRDE is installed, it
     28    can easily be enabled on a per-VM basis either in the VirtualBox Manager
     29    in the "Display" settings (see <xref linkend="settings-display" />) or
     30    with <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para>
    2731
    2832    <para>If you use <computeroutput>VBoxHeadless</computeroutput> (described
    29     further below), VRDP support will be automatically enabled since
     33    further below), RDP support will be automatically enabled since
    3034    VBoxHeadless has no other means of output.</para>
    3135
    … …  
    4044      number</emphasis> that the RDP server is using.</para>
    4145
    42       <para>By default, the VRDP server uses the standard RDP TCP port
     46      <para>By default, the VRDE uses the standard RDP TCP port
    4347      <computeroutput>3389</computeroutput>. You will need to change the
    44       default port if you run more than one VRDP server, since the port can
     48      default port if you run more than one RDP server, since the port can
    4549      only be used by one server at a time; you might also need to change it
    4650      on Windows hosts since the default port might already be used by the RDP
    … …  
    5357      <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
    5458      specify a comma-separated list of ports or ranges of ports. Use a dash
    55       between two port numbers to specify a range. The VRDP server will bind
    56       to <emphasis role="bold">one</emphasis> of available ports from the
     59      between two port numbers to specify a range. The VRDE will bind to
     60      <emphasis role="bold">one</emphasis> of available ports from the
    5761      specified list. For example, <computeroutput>VBoxManage modifyvm "VM
    58       name" --vrdpport 5000,5010-5012</computeroutput> will configure the
     62      name" --vrdeport 5000,5010-5012</computeroutput> will configure the
    5963      server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
    6064      linkend="vboxmanage-modifyvm" /> for details.</para>
    … …  
    8084            different port if necessary.</para>
    8185
    82             <note><para>When connecting to localhost in order to test the connection,
    83             the addresses <computeroutput>localhost</computeroutput> and
    84             <computeroutput>127.0.0.1</computeroutput> might not work using
    85             <computeroutput>mstsc.exe</computeroutput>. Instead, the address
    86             <computeroutput>127.0.0.2[:3389]</computeroutput> has to be used.</para></note>
     86            <note>
     87              <para>When connecting to localhost in order to test the
     88              connection, the addresses
     89              <computeroutput>localhost</computeroutput> and
     90              <computeroutput>127.0.0.1</computeroutput> might not work using
     91              <computeroutput>mstsc.exe</computeroutput>. Instead, the address
     92              <computeroutput>127.0.0.2[:3389]</computeroutput> has to be
     93              used.</para>
     94            </note>
    8795          </listitem>
    8896
    … …  
    120128
    121129    <sect2 id="vboxheadless">
    122       <title>VBoxHeadless, the VRDP-only server</title>
    123 
    124       <para>While the VRDP server that is built into the
    125       <computeroutput>VirtualBox</computeroutput> GUI is perfectly capable of
     130      <title>VBoxHeadless, the RDP-only server</title>
     131
     132      <para>While any VM started from the VirtualBox Manager is capable of
    126133      running virtual machines remotely, it is not convenient to have to run
    127       <computeroutput>VirtualBox</computeroutput> if you never want to have
    128       VMs displayed locally in the first place. In particular, if you are
    129       running servers whose only purpose is to host VMs, and all your VMs are
    130       supposed to run remotely over VRDP, then it is pointless to have a
    131       graphical user interface on the server at all -- especially since, on a
    132       Linux or Solaris host, <computeroutput>VirtualBox</computeroutput> comes
    133       with dependencies on the Qt and SDL libraries, which is inconvenient if
    134       you would rather not have the X Window system on your server at
    135       all.</para>
     134      the full-fledged GUI if you never want to have VMs displayed locally in
     135      the first place. In particular, if you are running servers whose only
     136      purpose is to host VMs, and all your VMs are supposed to run remotely
     137      over RDP, then it is pointless to have a graphical user interface on the
     138      server at all -- especially since, on a Linux or Solaris host,
     139      <computeroutput>VirtualBox</computeroutput> comes with dependencies on
     140      the Qt and SDL libraries, which is inconvenient if you would rather not
     141      have the X Window system on your server at all.</para>
    136142
    137143      <para>VirtualBox therefore comes with yet another front-end called
    138144      <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
    139       output on the host at all, but instead only delivers VRDP data.<footnote>
     145      output on the host at all, but instead only delivers RDP data.<footnote>
    140146          <para>Before VirtualBox 1.6, the headless server was called
    141147          <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
    … …  
    149155      <itemizedlist>
    150156        <listitem>
    151           <para>You can use <screen>VBoxManage startvm "VM name" --type vrdp</screen>
     157          <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>
    152158          The extra <computeroutput>--type</computeroutput> option causes the
    153159          VirtualBox core to use <computeroutput>VBoxHeadless</computeroutput>
    … …  
    171177      <para>Note that when you use
    172178      <computeroutput>VBoxHeadless</computeroutput> to start a VM, since the
    173       headless server has no other means of output, the built-in VRDP server
     179      headless server has no other means of output, the built-in RDP server
    174180      will <emphasis>always</emphasis> be enabled, regardless of whether you
    175181      have enabled the VRDP server in the VM's settings. If this is
    176182      undesirable (for example because you want to access the VM via
    177183      <computeroutput>ssh</computeroutput> only), start the VM like
    178       this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=off</screen>To
     184      this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde=off</screen>To
    179185      have the VRDP server use the setting from the VM configuration, as the
    180       other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrdp=config</screen></para>
     186      other front-ends would, use this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde=config</screen></para>
    181187    </sect2>
    182188
    … …  
    187193      <para>The following instructions may give you an idea how to create a
    188194      virtual machine on a headless server over a network connection. We will
    189       create a virtual machine, establish a VRDP connection and install a
     195      create a virtual machine, establish an RDP connection and install a
    190196      guest operating system -- all without having to touch the headless
    191197      server. All you need is the following:</para>
    … …  
    259265
    260266          <listitem>
    261             <para>Register the ISO file that contains the operating system
    262             installation that you want to install later:<screen>VBoxManage openmedium dvd /full/path/to/iso.iso</screen></para>
    263           </listitem>
    264 
    265           <listitem>
    266             <para>Attach this ISO to the virtual machine, so it can boot from
    267             it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
     267            <para>Attach the ISO file that contains the operating system
     268            installation that you want to install later to the virtual
     269            machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
    268270      --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
    269271          </listitem>
    … …  
    291293      <title>Remote USB</title>
    292294
    293       <para>As a special feature on top of the VRDP support, VirtualBox
    294       supports remote USB devices over the wire as well. That is, the
    295       VirtualBox guest that runs on one computer can access the USB devices of
    296       the remote computer on which the RDP data is being displayed the same
    297       way as USB devices that are connected to the actual host. This allows
    298       for running virtual machines on a VirtualBox host that acts as a server,
    299       where a client can connect from elsewhere that needs only a network
    300       adapter and a display capable of running an RDP viewer. When USB devices
    301       are plugged into the client, the remote VirtualBox server can access
    302       them.</para>
     295      <para>As a special feature on top of the Remote Desktop Extension,
     296      VirtualBox supports remote USB devices over the wire as well. That is,
     297      the VirtualBox guest that runs on one computer can access the USB
     298      devices of the remote computer on which the RDP data is being displayed
     299      the same way as USB devices that are connected to the actual host. This
     300      allows for running virtual machines on a VirtualBox host that acts as a
     301      server, where a client can connect from elsewhere that needs only a
     302      network adapter and a display capable of running an RDP viewer. When USB
     303      devices are plugged into the client, the remote VirtualBox server can
     304      access them.</para>
    303305
    304306      <para>For these remote USB devices, the same filter rules apply as for
    … …  
    378380            user running the VM.</para>
    379381          </listitem>
    380          
     382
    381383          <listitem>
    382384            <para>An additional library called
    383             <computeroutput>VBoxAuthSimple</computeroutput> performs authentication
    384             against credentials configured in the VM's extra data section. This is
    385             probably the simplest way to get authentication that does not depend
    386             on a running and supported guest (see below). In order to enable
    387             VBoxAuthSimple, issue
    388             <computeroutput>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</computeroutput>.
    389             To enable the library for a VM, switch authentication to external using
    390             <computeroutput>VBoxManage modifyvm "VM name" --vrdeauthtype external</computeroutput>.
    391             Last but not least, you have to configure users and passwords. Here is an example
    392             for the user "john" with the password "secret":
    393             <computeroutput>VBoxManage internalcommands passwordhash "secret"</computeroutput>
    394             This will give you the hash value "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
    395             which you set using
    396             <computeroutput>VBoxManage setextradata "VM name" "VBoxAuthSimple/users/john"
    397             "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"</computeroutput>.
    398             </para>
     385            <computeroutput>VBoxAuthSimple</computeroutput> performs
     386            authentication against credentials configured in the VM's extra
     387            data section. This is probably the simplest way to get
     388            authentication that does not depend on a running and supported
     389            guest (see below). In order to enable VBoxAuthSimple, issue
     390            <computeroutput>VBoxManage setproperty vrdeauthlibrary
     391            "VBoxAuthSimple"</computeroutput>. To enable the library for a VM,
     392            switch authentication to external using <computeroutput>VBoxManage
     393            modifyvm "VM name" --vrdeauthtype external</computeroutput>. Last
     394            but not least, you have to configure users and passwords. Here is
     395            an example for the user "john" with the password "secret":
     396            <computeroutput>VBoxManage internalcommands passwordhash
     397            "secret"</computeroutput> This will give you the hash value
     398            "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"
     399            which you set using <computeroutput>VBoxManage setextradata "VM
     400            name" "VBoxAuthSimple/users/john"
     401            "2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"</computeroutput>.</para>
    399402          </listitem>
    400403
    … …  
    407410          </listitem>
    408411        </itemizedlist></para>
    409        
    410         <para>In addition to the methods described above, you can replace the
    411         default "external authentication module with any other module. For this,
    412         VirtualBox provides a well-defined interface that allows you to write your
    413         own authentication module; see <xref linkend="vbox-authenticate-sdk" />
    414         for details.</para>
     412
     413      <para>In addition to the methods described above, you can replace the
     414      default "external authentication module with any other module. For this,
     415      VirtualBox provides a well-defined interface that allows you to write
     416      your own authentication module; see <xref
     417      linkend="vbox-authenticate-sdk" /> for details.</para>
    415418    </sect2>
    416419
    … …  
    460463
    461464    <sect2 id="vrdp-multiconnection">
    462       <title>Multiple VRDP connections</title>
     465      <title>Multiple RDP connections</title>
    463466
    464467      <para>The built-in RDP server of VirtualBox supports simultaneous
    … …  
    468471      computer at the same time, taking turns at the keyboard.</para>
    469472
    470       <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdpmulticon on</screen></para>
     473      <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
    471474    </sect2>
    472475
    … …  
    474477      <title>Multiple remote monitors</title>
    475478
    476       <para>
    477       To access two or more remote VM displays you have to enable the
    478       VRDP multiconnection mode (see <xref linkend="vrdp-multiconnection" />).</para>
     479      <para>To access two or more remote VM displays you have to enable the
     480      RDP multiconnection mode (see <xref
     481      linkend="vrdp-multiconnection" />).</para>
    479482
    480483      <para>The RDP client can select the virtual monitor number to connect to
    481         using the <computeroutput>domain</computeroutput> logon parameter
    482         (<computeroutput>-d</computeroutput>). If
    483       the parameter ends with <computeroutput>@</computeroutput> followed by a
    484       number, the VirtualBox RDP server interprets this number as the screen index.
    485       The primary guest screen is selected with
    486       <computeroutput>@1</computeroutput>, the first secondary screen is
    487       <computeroutput>@2</computeroutput>, etc.</para>
     484      using the <computeroutput>domain</computeroutput> logon parameter
     485      (<computeroutput>-d</computeroutput>). If the parameter ends with
     486      <computeroutput>@</computeroutput> followed by a number, the VirtualBox
     487      RDP server interprets this number as the screen index. The primary guest
     488      screen is selected with <computeroutput>@1</computeroutput>, the first
     489      secondary screen is <computeroutput>@2</computeroutput>, etc.</para>
    488490
    489491      <para>The MS RDP6 client does not let you specify a separate domain
    … …  
    499501      <title>VRDP video redirection</title>
    500502
    501       <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
     503      <para>Starting with VirtualBox 3.2, the RDP server can redirect video
    502504      streams from the guest to the RDP client. Video frames are compressed
    503505      using the JPEG algorithm allowing a higher compression ratio than
    … …  
    505507      compression ratio by lowering the video quality.</para>
    506508
    507       <para>Video streams in a guest are detected by the VRDP server
     509      <para>Video streams in a guest are detected by the RDP server
    508510      automatically as frequently updated rectangular areas. Therefore, this
    509511      method works with any guest operating system without having to install
    … …  
    515517      updates.</para>
    516518
    517       <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdpvideochannel on</screen></para>
     519      <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>
    518520
    519521      <para>The quality of the video is defined as a value from 10 to 100
    … …  
    523525
    524526    <sect2 id="vrdp-customization">
    525       <title>VRDP customization</title>
    526 
    527       <para>Starting with VirtualBox 3.2.10, it is possible to disable display output,
    528       mouse and keyboard input, audio, remote USB or clipboard in the VRDP server.</para>
    529 
    530       <para>The following commands change corresponding server settings:</para>
     527      <title>VRDE customization</title>
     528
     529      <para>Starting with VirtualBox 3.2.10, it is possible to disable display
     530      output, mouse and keyboard input, audio, remote USB or clipboard in the
     531      RDP server.</para>
     532
     533      <para>The following commands change corresponding server
     534      settings:</para>
    531535
    532536      <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
    … …  
    536540VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
    537541
    538       <para>To reenable a feature use a similar command without the trailing 1. For example:
    539       <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
     542      <para>To reenable a feature use a similar command without the trailing
     543      1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
    540544    </sect2>
    541545  </sect1>
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette