source: vbox/trunk/doc/manual/en_US/user_GuestAdditions.xml@ 74929

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<chapter id="guestadditions">

  <title>Guest Additions</title>

  <para>
    The previous chapter covered getting started with VirtualBox and
    installing operating systems in a virtual machine. For any serious
    and interactive use, the VirtualBox Guest Additions will make your
    life much easier by providing closer integration between host and
    guest and improving the interactive performance of guest systems.
    This chapter describes the Guest Additions in detail.
  </para>

  <sect1 id="guestadd-intro">

    <title>Introduction to Guest Additions</title>

    <para>
      As mentioned in <xref linkend="virtintro" />, the Guest Additions
      are designed to be installed <emphasis>inside</emphasis> a virtual
      machine after the guest operating system has been installed. They
      consist of device drivers and system applications that optimize
      the guest operating system for better performance and usability.
      See <xref
    linkend="guestossupport" /> for details on what
      guest operating systems are fully supported with Guest Additions
      by VirtualBox.
    </para>

    <para>
      The VirtualBox Guest Additions for all supported guest operating
      systems are provided as a single CD-ROM image file which is called
      <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This
      image file is located in the installation directory of VirtualBox.
      To install the Guest Additions for a particular VM, you mount this
      ISO file in your VM as a virtual CD-ROM and install from there.
    </para>

    <para>
      The Guest Additions offer the following features:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Mouse pointer integration</emphasis>. To
          overcome the limitations for mouse support described in
          <xref linkend="keyb_mouse_normal" />, this feature provides
          you with seamless mouse support. You will only have one mouse
          pointer and pressing the Host key is no longer required to
          "free" the mouse from being captured by the guest OS. To make
          this work, a special mouse driver is installed in the guest
          that communicates with the "real" mouse driver on your host
          and moves the guest mouse pointer accordingly.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Shared folders.</emphasis> These provide
          an easy way to exchange files between the host and the guest.
          Much like ordinary Windows network shares, you can tell
          VirtualBox to treat a certain host directory as a shared
          folder, and VirtualBox will make it available to the guest
          operating system as a network share, irrespective of whether
          guest actually has a network. See
          <xref
            linkend="sharedfolders" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Better video support.</emphasis> While
          the virtual graphics card which VirtualBox emulates for any
          guest operating system provides all the basic features, the
          custom video drivers that are installed with the Guest
          Additions provide you with extra high and non-standard video
          modes, as well as accelerated video performance.
        </para>

        <para>
          In addition, with Windows, Linux, and Solaris guests, you can
          resize the virtual machine's window if the Guest Additions are
          installed. The video resolution in the guest will be
          automatically adjusted, as if you had manually entered an
          arbitrary resolution in the guest's display settings. See
          <xref
            linkend="intro-resize-window" />.
        </para>

        <para>
          If the Guest Additions are installed, 3D graphics and 2D video
          for guest applications can be accelerated. See
          <xref
            linkend="guestadd-video" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Seamless windows.</emphasis> With this
          feature, the individual windows that are displayed on the
          desktop of the virtual machine can be mapped on the host's
          desktop, as if the underlying application was actually running
          on the host. See <xref linkend="seamlesswindows" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Generic host/guest communication
          channels.</emphasis> The Guest Additions enable you to control
          and monitor guest execution. The "guest properties" provide a
          generic string-based mechanism to exchange data bits between a
          guest and a host, some of which have special meanings for
          controlling and monitoring the guest. See
          <xref linkend="guestadd-guestprops" />.
        </para>

        <para>
          Additionally, applications can be started in a guest from the
          host. See <xref linkend="guestadd-guestcontrol" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Time synchronization.</emphasis> With
          the Guest Additions installed, VirtualBox can ensure that the
          guest's system time is better synchronized with that of the
          host.
        </para>

        <para>
          For various reasons, the time in the guest might run at a
          slightly different rate than the time on the host. The host
          could be receiving updates via NTP and its own time might not
          run linearly. A VM could also be paused, which stops the flow
          of time in the guest for a shorter or longer period of time.
          When the wall clock time between the guest and host only
          differs slightly, the time synchronization service attempts to
          gradually and smoothly adjust the guest time in small
          increments to either "catch up" or "lose" time. When the
          difference is too great, for example if a VM paused for hours
          or restored from saved state, the guest time is changed
          immediately, without a gradual adjustment.
        </para>

        <para>
          The Guest Additions will resynchronize the time regularly. See
          <xref linkend="changetimesync" /> for how to configure the
          parameters of the time synchronization mechanism.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Shared clipboard.</emphasis> With the
          Guest Additions installed, the clipboard of the guest
          operating system can optionally be shared with your host
          operating system. See <xref linkend="generalsettings" />.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Automated logons.</emphasis> Also called
          credentials passing. See <xref linkend="autologon" />.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      Each version of VirtualBox, even minor releases, ship with their
      own version of the Guest Additions. While the interfaces through
      which the VirtualBox core communicates with the Guest Additions
      are kept stable so that Guest Additions already installed in a VM
      should continue to work when VirtualBox is upgraded on the host,
      for best results, it is recommended to keep the Guest Additions at
      the same version.
    </para>

    <para>
      Starting with VirtualBox 3.1, the Windows and Linux Guest
      Additions therefore check automatically whether they have to be
      updated. If the host is running a newer VirtualBox version than
      the Guest Additions, a notification with further instructions is
      displayed in the guest.
    </para>

    <para>
      To disable this update check for the Guest Additions of a given
      virtual machine, set the value of its
      <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
      guest property to <computeroutput>0</computeroutput>. See
      <xref
    linkend="guestadd-guestprops" />.
    </para>

  </sect1>

  <sect1 id="guestadd-install">

    <title>Installing and Maintaining Guest Additions</title>

    <para>
      Guest Additions are available for virtual machines running
      Windows, Linux, Solaris, or OS/2. The following sections describe
      the specifics of each variant in detail.
    </para>

    <sect2 id="additions-windows">

      <title>Guest Additions for Windows</title>

      <para>
        The VirtualBox Windows Guest Additions are designed to be
        installed in a virtual machine running a Windows operating
        system. The following versions of Windows guests are supported:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Microsoft Windows NT 4.0 (any service pack)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows 2000 (any service pack)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows XP (any service pack)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows Server 2003 (any service pack)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows Server 2008
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows Vista (all editions)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows 7 (all editions)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows 8 (all editions)
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows 10 RTM build 10240
          </para>
        </listitem>

        <listitem>
          <para>
            Microsoft Windows Server 2012
          </para>
        </listitem>

      </itemizedlist>

      <sect3 id="mountingadditionsiso">

        <title>Installing the Windows Guest Additions</title>

        <para>
          In the Devices menu in the virtual machine's menu bar,
          VirtualBox has a menu item <emphasis role="bold">Insert Guest
          Additions CD Image</emphasis>, which mounts the Guest
          Additions ISO file inside your virtual machine. A Windows
          guest should then automatically start the Guest Additions
          installer, which installs the Guest Additions into your
          Windows guest. Other guest operating systems, or if automatic
          start of software on CD is disabled, need a manual start of
          the installer.
        </para>

        <note>
          <para>
            For the basic Direct3D acceleration to work in a Windows
            guest, you have to install the WDDM video driver available
            for Windows Vista or higher.

            <footnote>

              <para>
                An experimental WDDM driver was added with VirtualBox
                4.1.
              </para>

            </footnote>

            For Windows 8 and higher only the WDDM Direct3D video driver
            is available. For basic Direct3D acceleration to work in
            Windows XP guests, you have to install the Guest Additions
            in Safe Mode. See <xref linkend="KnownIssues" /> for
            details.
          </para>
        </note>

        <para>
          If you prefer to mount the Guest Additions manually, you can
          perform the following steps:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Start the virtual machine in which you have installed
              Windows.
            </para>
          </listitem>

          <listitem>
            <para>
              Select <emphasis role="bold">Mount CD/DVD-ROM</emphasis>
              from the Devices menu in the virtual machine's menu bar
              and then <emphasis role="bold">CD/DVD-ROM
              Image</emphasis>. This displays the Virtual Media Manager,
              described in <xref
            linkend="vdis" />.
            </para>
          </listitem>

          <listitem>
            <para>
              In the Virtual Media Manager, click
              <emphasis role="bold">Add</emphasis> and browse your host
              file system for the
              <computeroutput>VBoxGuestAdditions.iso</computeroutput>
              file.
            </para>

            <itemizedlist>

              <listitem>
                <para>
                  On a Windows host, this file is in the VirtualBox
                  installation directory, usually in
                  <computeroutput>C:\Program
                  files\Oracle\VirtualBox</computeroutput>.
                </para>
              </listitem>

              <listitem>
                <para>
                  On Mac OS X hosts, this file is in the application
                  bundle of VirtualBox. Right-click on the VirtualBox
                  icon in Finder and choose <emphasis role="bold">Show
                  Package Contents</emphasis>. The file is located in
                  the <computeroutput>Contents/MacOS</computeroutput>
                  folder.
                </para>
              </listitem>

              <listitem>
                <para>
                  On a Linux host, this file is in the
                  <computeroutput>additions</computeroutput> folder
                  where you installed VirtualBox, usually
                  <computeroutput>/opt/VirtualBox/</computeroutput>.
                </para>
              </listitem>

              <listitem>
                <para>
                  On Solaris hosts, this file is in the
                  <computeroutput>additions</computeroutput> folder
                  where you installed VirtualBox, usually
                  <computeroutput>/opt/VirtualBox</computeroutput>.
                </para>
              </listitem>

            </itemizedlist>
          </listitem>

          <listitem>
            <para>
              In the Virtual Media Manager, select the ISO file and
              click <emphasis role="bold">Select</emphasis> button. This
              mounts the ISO file and presents it to your Windows guest
              as a CD-ROM.
            </para>
          </listitem>

        </orderedlist>

        <para>
          Unless you have the Autostart feature disabled in your Windows
          guest, Windows will now autostart the VirtualBox Guest
          Additions installation program from the Additions ISO. If the
          Autostart feature has been turned off, choose
          <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from
          the CD/DVD drive inside the guest to start the installer.
        </para>

        <para>
          The installer will add several device drivers to the Windows
          driver database and then invoke the hardware detection wizard.
        </para>

        <para>
          Depending on your configuration, it might display warnings
          that the drivers are not digitally signed. You must confirm
          these in order to continue the installation and properly
          install the Additions.
        </para>

        <para>
          After installation, reboot your guest operating system to
          activate the Additions.
        </para>

      </sect3>

      <sect3 id="additions-windows-updating">

        <title>Updating the Windows Guest Additions</title>

        <para>
          Windows Guest Additions can be updated by running the
          installation program again. This replaces the previous
          Additions drivers with updated versions.
        </para>

        <para>
          Alternatively, you can also open the Windows Device Manager
          and select <emphasis role="bold">Update Driver...</emphasis>
          for the following devices:
        </para>

        <orderedlist>

          <listitem>
            <para>
              VirtualBox Graphics Adapter
            </para>
          </listitem>

          <listitem>
            <para>
              VirtualBox System Device
            </para>
          </listitem>

        </orderedlist>

        <para>
          For each, choose the option to provide your own driver, click
          <emphasis role="bold">Have Disk</emphasis> and navigate to the
          CD-ROM drive with the Guest Additions.
        </para>

      </sect3>

      <sect3 id="additions-windows-install-unattended">

        <title>Unattended Installation</title>

        <para>
          As a prerequisite for avoid popups while performing an
          unattended installation of the VirtualBox Guest Additions, the
          code signing certificates used to sign the drivers needs to be
          installed in the right certificates stores in the guest
          system. Failing to do this will cause a typical windows
          installation to pop up a dialog asking whether its allowable
          to install each driver.
        </para>

        <note>
          <para>
            On some Windows versions like Windows 2000 and Windows XP
            the user intervention popups mentioned above always will be
            displayed, even after importing the Oracle certificates.
          </para>
        </note>

        <para>
          Since VirtualBox 4.2, installing the code signing certificates
          on a Windows guest can be done in an automated fashion using
          the <computeroutput>VBoxCertUtil.exe</computeroutput> utility
          found on the Guest Additions installation CD in the
          <computeroutput>cert</computeroutput> folder:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Log in as Administrator on the guest.
            </para>
          </listitem>

          <listitem>
            <para>
              Mount the VirtualBox Guest Additions .ISO.
            </para>
          </listitem>

          <listitem>
            <para>
              Open a command line window on the guest and change to the
              <computeroutput>cert</computeroutput> folder on the
              VirtualBox Guest Additions CD.
            </para>
          </listitem>

          <listitem>
            <para>
              Run the following command:
            </para>

<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen>

            <para>
              This command installs the certificates to the certificate
              store. When installing the same certificate more than
              once, an appropriate error will be displayed.
            </para>
          </listitem>

        </orderedlist>

        <para>
          Prior to VirtualBox 4.2 the code signing certificates need to
          be imported in more manual style using the
          <computeroutput>certutil.exe</computeroutput> utility, which
          is shipped since Windows Vista. For Windows versions before
          Vista you need to download and install
          <computeroutput>certutil.exe</computeroutput> manually. Since
          the certificates are not accompanied on the VirtualBox Guest
          Additions CD-ROM prior to 4.2, these need to get extracted
          from a signed VirtualBox executable first.
        </para>

        <para>
          In the following examples the required certificates are
          extracted from the VirtualBox Windows Guest Additions
          installer on the CD-ROM.
        </para>

        <para>
          For a VeriSign Code Signing CA certificate, do the following:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Open the Windows Explorer.
            </para>
          </listitem>

          <listitem>
            <para>
              Right click on
              VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe,
              and choose <emphasis role="bold">Properties</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              Go to the Digital Signatures tab, choose
              <emphasis role="bold">Oracle Corporation</emphasis> and
              click on <emphasis role="bold">Details</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              On the General tab, click on <emphasis role="bold">View
              Certificate</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              On the Certification Path tab, select
              <emphasis role="bold">VeriSign Class 3 Public Primary
              CA</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              Click <emphasis role="bold">View Certificate</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              On the Details tab, click <emphasis role="bold">Copy to
              File</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              In the displayed wizard choose <emphasis role="bold">DER
              Encoded Binary X.509 (.CER)</emphasis> and save the
              certificate file to a local path. Close the wizard.
            </para>
          </listitem>

          <listitem>
            <para>
              Close the certificate dialog for Verisign Class 3 Code
              Signing 2010 CA.
            </para>
          </listitem>

        </orderedlist>

        <para>
          For an Oracle Corporation CA certificate, do the following:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Open the Windows Explorer.
            </para>
          </listitem>

          <listitem>
            <para>
              Right-click on
              VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe
              and choose <emphasis role="bold">Properties</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              Go to the Digital Signatures tab, choose
              <emphasis role="bold">Oracle Corporation</emphasis> and
              click on <emphasis role="bold">Details</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              On the General tab, click on <emphasis role="bold">View
              Certificate</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              On the Details tab, click on <emphasis role="bold">Copy to
              File</emphasis>.
            </para>
          </listitem>

          <listitem>
            <para>
              In the displayed wizard choose <emphasis role="bold">DER
              Encoded Binary X.509 (.CER)</emphasis> and save the
              certificate file to a local path. Close the wizard
            </para>
          </listitem>

          <listitem>
            <para>
              Close the certificate dialog for Oracle Corporation.
            </para>
          </listitem>

        </orderedlist>

        <para>
          After exporting the two certificates above they can be
          imported into the certificate store using the
          <computeroutput>certutil.exe</computeroutput> utility, as
          follows:
        </para>

<screen>certutil -addstore -f Root "&lt;Path to
          exported certificate file&gt;"</screen>

        <para>
          In order to allow for completely unattended guest
          installations, you can specify a command line parameter to the
          install launcher:
        </para>

<screen>VBoxWindowsAdditions.exe /S</screen>

        <para>
          This automatically installs the right files and drivers for
          the corresponding platform, 32-bit or 64-bit.
        </para>

        <note>
          <para>
            By default on an unattended installation on a Vista or
            Windows 7 guest, there will be the XPDM graphics driver
            installed. This graphics driver does not support Windows
            Aero / Direct3D on the guest. Instead, the WDDM graphics
            driver needs to be installed. To select this driver by
            default, add the command line parameter
            <computeroutput>/with_wddm</computeroutput> when invoking
            the Windows Guest Additions installer. This is only required
            for Vista and Windows 7.
          </para>
        </note>

        <note>
          <para>
            For Windows Aero to run correctly on a guest, the guest's
            VRAM size needs to be configured to at least 128 MB.
          </para>
        </note>

        <para>
          For more options regarding unattended guest installations,
          consult the command line help by using the command:
        </para>

<screen>VBoxWindowsAdditions.exe /?</screen>

      </sect3>

      <sect3 id="windows-guest-file-extraction">

        <title>Manual file Extraction</title>

        <para>
          If you would like to install the files and drivers manually,
          you can extract the files from the Windows Guest Additions
          setup as follows
        </para>

<screen>VBoxWindowsAdditions.exe /extract</screen>

        <para>
          To explicitly extract the Windows Guest Additions for another
          platform than the current running one, such as 64-bit files on
          a 32-bit system, you must use the appropriate platform
          installer. Use
          <computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput>
          or
          <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>
          with the <computeroutput>/extract</computeroutput> parameter.
        </para>

      </sect3>

    </sect2>

    <sect2 id="additions-linux">

      <title>Guest Additions for Linux</title>

      <para>
        Like the Windows Guest Additions, the VirtualBox Guest Additions
        for Linux are a set of device drivers and system applications
        which may be installed in the guest operating system.
      </para>

      <para>
        The following Linux distributions are officially supported:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Oracle Linux as of version 5, including UEK kernels
          </para>
        </listitem>

        <listitem>
          <para>
            Fedora as of Fedora Core 4
          </para>
        </listitem>

        <listitem>
          <para>
            Redhat Enterprise Linux as of version 3
          </para>
        </listitem>

        <listitem>
          <para>
            SUSE and openSUSE Linux as of version 9
          </para>
        </listitem>

        <listitem>
          <para>
            Ubuntu as of version 5.10
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Many other distributions are known to work with the Guest
        Additions.
      </para>

      <para>
        The version of the Linux kernel supplied by default in SUSE and
        openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06
        (server edition) contains a bug which can cause it to crash
        during startup when it is run in a virtual machine. The Guest
        Additions work in those distributions.
      </para>

      <para>
        Note that some Linux distributions already come with all or part
        of the VirtualBox Guest Additions. You may choose to keep the
        distribution's version of the Guest Additions but these are
        often not up to date and limited in functionality, so we
        recommend replacing them with the Guest Additions that come with
        VirtualBox. The VirtualBox Linux Guest Additions installer tries
        to detect existing installation and replace them but depending
        on how the distribution integrates the Guest Additions, this may
        require some manual interaction. It is highly recommended to
        take a snapshot of the virtual machine before replacing
        pre-installed Guest Additions.
      </para>

      <sect3 id="additions-linux-install">

        <title>Installing the Linux Guest Additions</title>

        <para>
          The VirtualBox Guest Additions for Linux are provided on the
          same virtual CD-ROM file as the Guest Additions for Windows.
          See <xref linkend="mountingadditionsiso"/>. They also come
          with an installation program that guides you through the setup
          process. However, due to the significant differences between
          Linux distributions, installation may be slightly more complex
          when compared to Windows.
        </para>

        <para>
          Installation generally involves the following steps:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Before installing the Guest Additions, you prepare your
              guest system for building external kernel modules. This
              works as described in
              <xref
            linkend="externalkernelmodules" />,
              except that this step must be performed in your Linux
              <emphasis>guest</emphasis> instead of on a Linux host
              system.
            </para>

            <para>
              If you suspect that something has gone wrong, check that
              your guest is set up correctly and run the following
              command as root:
            </para>

<screen>rcvboxadd setup</screen>
          </listitem>

          <listitem>
            <para>
              Insert the
              <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD
              file into your Linux guest's virtual CD-ROM drive, as
              described for a Windows guest in
              <xref
            linkend="mountingadditionsiso" />.
            </para>
          </listitem>

          <listitem>
            <para>
              Change to the directory where your CD-ROM drive is mounted
              and run the following command as root:
            </para>

<screen>sh ./VBoxLinuxAdditions.run</screen>
          </listitem>

        </orderedlist>

      </sect3>

      <sect3 id="additions-linux-graphics-mouse">

        <title>Graphics and Mouse Integration</title>

        <para>
          In Linux and Solaris guests, VirtualBox graphics and mouse
          integration goes through the X Window System. VirtualBox can
          use the X.Org variant of the system, or XFree86 version 4.3
          which is identical to the first X.Org release. During the
          installation process, the X.Org display server will be set up
          to use the graphics and mouse drivers which come with the
          Guest Additions.
        </para>

        <para>
          After installing the Guest Additions into a fresh installation
          of a supported Linux distribution or Solaris system, many
          unsupported systems will work correctly too, the guest's
          graphics mode will change to fit the size of the VirtualBox
          window on the host when it is resized. You can also ask the
          guest system to switch to a particular resolution by sending a
          video mode hint using the
          <computeroutput>VBoxManage</computeroutput> tool.
        </para>

        <para>
          Multiple guest monitors are supported in guests using the
          X.Org server version 1.3, which is part of release 7.3 of the
          X Window System version 11, or a later version. The layout of
          the guest screens can be adjusted as needed using the tools
          which come with the guest operating system.
        </para>

        <para>
          If you want to understand more about the details of how the
          X.Org drivers are set up, in particular if you wish to use
          them in a setting which our installer does not handle
          correctly, see <xref linkend="guestxorgsetup" />.
        </para>

      </sect3>

      <sect3 id="additions-linux-updating">

        <title>Updating the Linux Guest Additions</title>

        <para>
          The Guest Additions can simply be updated by going through the
          installation procedure again with an updated CD-ROM image.
          This will replace the drivers with updated versions. You
          should reboot after updating the Guest Additions.
        </para>

      </sect3>

      <sect3 id="additions-linux-uninstall">

        <title>Uninstalling the Linux Guest Additions</title>

        <para>
          If you have a version of the Guest Additions installed on your
          virtual machine and wish to remove it without installing new
          ones, you can do so by inserting the Guest Additions CD image
          into the virtual CD-ROM drive as described above and running
          the installer for the current Guest Additions with the
          <computeroutput>uninstall</computeroutput> parameter from the
          path that the CD image is mounted on in the guest:

<screen>sh ./VBoxLinuxAdditions.run uninstall</screen>
        </para>

        <para>
          While this will normally work without issues, you may need to
          do some manual cleanup of the guest in some cases, especially
          of the XFree86Config or xorg.conf file. In particular, if the
          Additions version installed or the guest operating system were
          very old, or if you made your own changes to the Guest
          Additions setup after you installed them.
        </para>

        <para>
          Starting with version 3.1.0, you can uninstall the Additions
          as follows:
        </para>

<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen>

        <para>
          Replace
          <computeroutput>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></computeroutput>
          with the correct Guest Additions installation directory.
        </para>

      </sect3>

    </sect2>

    <sect2 id="additions-solaris">

      <title>Guest Additions for Solaris</title>

      <para>
        Like the Windows Guest Additions, the VirtualBox Guest Additions
        for Solaris take the form of a set of device drivers and system
        applications which may be installed in the guest operating
        system.
      </para>

      <para>
        The following Solaris distributions are officially supported:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Solaris 11, including Solaris 11 Express
          </para>
        </listitem>

        <listitem>
          <para>
            Solaris 10 u5 and higher
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Other distributions may work if they are based on comparable
        software releases.
      </para>

      <sect3 id="additions-solaris-install">

        <title>Installing the Solaris Guest Additions</title>

        <para>
          The VirtualBox Guest Additions for Solaris are provided on the
          same ISO CD-ROM as the Additions for Windows and Linux. They
          come with an installation program that guides you through the
          setup process.
        </para>

        <para>
          Installation involves the following steps:
        </para>

        <orderedlist>

          <listitem>
            <para>
              Mount the
              <computeroutput>VBoxGuestAdditions.iso</computeroutput>
              file as your Solaris guest's virtual CD-ROM drive, exactly
              the same way as described for a Windows guest in
              <xref
            linkend="mountingadditionsiso" />.
            </para>

            <para>
              If the CD-ROM drive on the guest does not get mounted, as
              seen with some versions of Solaris 10, run the following
              command as root:
            </para>

<screen>svcadm restart volfs</screen>
          </listitem>

          <listitem>
            <para>
              Change to the directory where your CD-ROM drive is mounted
              and run the following command as root:
            </para>

<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen>
          </listitem>

          <listitem>
            <para>
              Choose <emphasis role="bold">1</emphasis> and confirm
              installation of the Guest Additions package. After the
              installation is complete, log out and log in to X server
              on your guest, to activate the X11 Guest Additions.
            </para>
          </listitem>

        </orderedlist>

      </sect3>

      <sect3 id="additions-solaris-uninstall">

        <title>Uninstalling the Solaris Guest Additions</title>

        <para>
          The Solaris Guest Additions can be safely removed by removing
          the package from the guest. Open a root terminal session and
          run the following command:
        </para>

        <para>
<screen>pkgrm SUNWvboxguest</screen>
        </para>

      </sect3>

      <sect3 id="additions-solaris-updating">

        <title>Updating the Solaris Guest Additions</title>

        <para>
          The Guest Additions should be updated by first uninstalling
          the existing Guest Additions and then installing the new ones.
          Attempting to install new Guest Additions without removing the
          existing ones is not possible.
        </para>

      </sect3>

    </sect2>

    <sect2 id="additions-os2">

      <title>Guest Additions for OS/2</title>

      <para>
        VirtualBox also ships with a set of drivers that improve running
        OS/2 in a virtual machine. Due to restrictions of OS/2 itself,
        this variant of the Guest Additions has a limited feature set.
        See <xref
      linkend="KnownIssues" /> for details.
      </para>

      <para>
        The OS/2 Guest Additions are provided on the same ISO CD-ROM as
        those for the other platforms. Mount the ISO in OS/2 as
        described previously. The OS/2 Guest Additions are located in
        the directory <computeroutput>\32bit\OS2</computeroutput>.
      </para>

      <para>
        We do not provide an automatic installer at this time. See the
        <computeroutput>readme.txt</computeroutput> file in the CD-ROM
        directory, which describes how to install the OS/2 Guest
        Additions manually.
      </para>

    </sect2>

  </sect1>

  <sect1 id="sharedfolders">

    <title>Shared Folders</title>

    <para>
      With the <emphasis>shared folders</emphasis> feature of
      VirtualBox, you can access files of your host system from within
      the guest system. This is similar how you would use network shares
      in Windows networks, except that shared folders do not need
      require networking, only the Guest Additions. Shared Folders are
      supported with Windows 2000 or later, Linux, and Solaris guests.
    </para>

    <para>
      Shared folders must physically reside on the
      <emphasis>host</emphasis> and are then shared with the guest,
      which uses a special file system driver in the Guest Addition to
      talk to the host. For Windows guests, shared folders are
      implemented as a pseudo-network redirector. For Linux and Solaris
      guests, the Guest Additions provide a virtual file system.
    </para>

    <para>
      To share a host folder with a virtual machine in VirtualBox, you
      must specify the path of that folder and choose for it a
      <emphasis>share nam</emphasis>e that the guest can use to access
      it. Hence, first create the shared folder on the host. Then,
      within the guest, you can connect to it.
    </para>

    <para>
      There are several ways in which shared folders can be set up for a
      particular virtual machine:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          In the window of a running VM, you select
          <emphasis role="bold">Shared Folders</emphasis> from the
          <emphasis role="bold">Devices</emphasis> menu, or click on the
          folder icon on the status bar in the bottom right corner.
        </para>
      </listitem>

      <listitem>
        <para>
          If a VM is not currently running, you can configure shared
          folders in each virtual machine's Settings dialog.
        </para>
      </listitem>

      <listitem>
        <para>
          From the command line, you can create shared folders using
          VBoxManage, as follows:
        </para>

<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen>

        <para>
          See <xref linkend="vboxmanage-sharedfolder" />.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      There are two types of shares:
    </para>

    <orderedlist>

      <listitem>
        <para>
          VM shares which are only available to the VM for which they
          have been defined.
        </para>
      </listitem>

      <listitem>
        <para>
          Transient VM shares, which can be added and removed at runtime
          and do not persist after a VM has stopped. For these, add the
          <computeroutput>--transient</computeroutput> option to the
          above command line.
        </para>
      </listitem>

    </orderedlist>

    <para>
      Shared folders have read/write access to the files at the host
      path by default. To restrict the guest to have read-only access,
      create a read-only shared folder. This can either be achieved
      using the GUI or by appending the parameter
      <computeroutput>--readonly</computeroutput> when creating the
      shared folder with VBoxManage.
    </para>

    <para>
      Starting with version 4.0, VirtualBox shared folders also support
      symbolic links (<emphasis>symlinks</emphasis>), under the
      following conditions:
    </para>

    <orderedlist>

      <listitem>
        <para>
          The host operating system must support symlinks. For example,
          a Mac OS X, Linux, or Solaris host is required.
        </para>
      </listitem>

      <listitem>
        <para>
          Currently only Linux and Solaris Guest Additions support
          symlinks.
        </para>
      </listitem>

      <listitem>
        <para>
          For security reasons the guest OS is not allowed to create
          symlinks by default. If you trust the guest OS to not abuse
          the functionality, you can enable creation of symlinks for a
          shared folder as follows:
        </para>

<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen>
      </listitem>

    </orderedlist>

    <sect2 id="sf_mount_manual">

      <title>Manual Mounting</title>

      <para>
        You can mount the shared folder from inside a VM, in the same
        way as you would mount an ordinary network share:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            In a Windows guest, shared folders are browseable and
            therefore visible in Windows Explorer. To attach the host's
            shared folder to your Windows guest, open Windows Explorer
            and look for the folder in <emphasis role="bold">My
            Networking Place</emphasis>s, <emphasis role="bold">Entire
            Network</emphasis>, <emphasis role="bold">VirtualBox Shared
            Folders</emphasis>. By right-clicking on a shared folder and
            selecting <emphasis role="bold">Map Network Drive</emphasis>
            from the menu that pops up, you can assign a drive letter to
            that shared folder.
          </para>

          <para>
            Alternatively, on the Windows command line, use the
            following command:
          </para>

<screen>net use x: \\vboxsvr\sharename</screen>

          <para>
            While <computeroutput>vboxsvr</computeroutput> is a fixed
            name, note that <computeroutput>vboxsrv</computeroutput>
            would also work, replace <replaceable>x:</replaceable> with
            the drive letter that you want to use for the share, and
            <replaceable>sharename</replaceable> with the share name
            specified with <computeroutput>VBoxManage</computeroutput>.
          </para>
        </listitem>

        <listitem>
          <para>
            In a Linux guest, use the following command:
          </para>

<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>

          <para>
            To mount a shared folder during boot, add the following
            entry to <computeroutput>/etc/fstab</computeroutput>:
          </para>

<screen>sharename   mountpoint   vboxsf   defaults  0   0</screen>
        </listitem>

        <listitem>
          <para>
            In a Solaris guest, use the following command:
          </para>

<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>

          <para>
            Replace <replaceable>sharename</replaceable>, use a
            lowercase string, with the share name specified with
            <computeroutput>VBoxManage</computeroutput> or the GUI.
            Replace <replaceable>mountpoint</replaceable> with the path
            where you want the share to be mounted on the guest, such as
            <computeroutput>/mnt/share</computeroutput>. The usual mount
            rules apply. For example, create this directory first if it
            does not exist yet.
          </para>

          <para>
            Here is an example of mounting the shared folder for the
            user jack on Solaris:
          </para>

<screen>$ id
uid=5000(jack) gid=1(other)
$ mkdir /export/home/jack/mount
$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount
$ cd ~/mount
$ ls
sharedfile1.mp3 sharedfile2.txt
$</screen>

          <para>
            Beyond the standard options supplied by the
            <computeroutput>mount</computeroutput> command, the
            following are available:
          </para>

<screen>iocharset CHARSET</screen>

          <para>
            This option sets the character set used for I/O operations.
            Note that on Linux guests, if the
            <computeroutput>iocharset</computeroutput> option is not
            specified, then the Guest Additions driver will attempt to
            use the character set specified by the CONFIG_NLS_DEFAULT
            kernel option. If this option is not set either, then UTF-8
            is used.
          </para>

<screen>convertcp CHARSET</screen>

          <para>
            This option specifies the character set used for the shared
            folder name. This is UTF-8 by default.
          </para>

          <para>
            The generic mount options, documented in the
            <computeroutput>mount</computeroutput> manual page, apply
            also. Especially useful are the options
            <computeroutput>uid</computeroutput>,
            <computeroutput>gid</computeroutput> and
            <computeroutput>mode</computeroutput>, as they can allow
            access by normal users in read/write mode, depending on the
            settings, even if root has mounted the filesystem.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="sf_mount_auto">

      <title>Automatic Mounting</title>

      <para>
        Starting with version 4.0, VirtualBox provides the option to
        mount shared folders automatically If automatic mounting is
        enabled for a specific shared folder, the Guest Additions will
        automatically mount that folder as soon as a user logs in to the
        guest OS. The details depend on the guest OS type, as follows:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Windows guests.</emphasis> Any
            auto-mounted shared folder will receive its own drive
            letter, such as <computeroutput>E:</computeroutput>,
            depending on the free drive letters remaining in the guest.
          </para>

          <para>
            If there are no free drive letters left, auto-mounting will
            fail. As a result, the number of auto-mounted shared folders
            is typically limited to 22 or less with Windows guests.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Linux guests.</emphasis> Auto-mounted
            shared folders are mounted into the
            <computeroutput>/media</computeroutput> directory, along
            with the prefix <computeroutput>sf_</computeroutput>. For
            example, the shared folder
            <computeroutput>myfiles</computeroutput> would be mounted to
            <computeroutput>/media/sf_myfiles</computeroutput> on Linux
            and <computeroutput>/mnt/sf_myfiles</computeroutput> on
            Solaris.
          </para>

          <para>
            The guest property
            <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
            determines the prefix that is used. Change that guest
            property to a value other than
            <computeroutput>sf</computeroutput> to use another prefix.
            See <xref
            linkend="guestadd-guestprops" />.
          </para>

          <note>
            <para>
              Access to auto-mounted shared folders is only granted to
              the user group <computeroutput>vboxsf</computeroutput>,
              which is created by the VirtualBox Guest Additions
              installer. Therefore, guest users have to be member of
              that group to have read/write access, or to have read-only
              access if the folder is not mapped writable.
            </para>
          </note>

          <para>
            To change the mount directory to something other than
            <computeroutput>/media</computeroutput>, you can set the
            guest property
            <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Solaris guests</emphasis> behave like
            Linux guests, except that
            <computeroutput>/mnt</computeroutput> is used as the default
            mount directory instead of
            <computeroutput>/media</computeroutput>.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        To have any changes to auto-mounted shared folders applied while
        a VM is running, the guest OS needs to be rebooted. This applies
        only to auto-mounted shared folders, not the ones which are
        mounted manually.
      </para>

    </sect2>

  </sect1>

  <sect1 id="guestadd-dnd">

    <title>Drag and Drop</title>

    <para>
      Starting with version 5.0, VirtualBox enables you to drag and drop
      content from the host to the guest, and vice versa. For this to
      work the latest Guest Additions must be installed on the guest.
    </para>

    <para>
      Drag and drop transparently allows copying or opening files,
      directories, and even certain clipboard formats from one end to
      the other. for example, from the host to the guest or from the
      guest to the host. You then can perform drag and drop operations
      between the host and a VM, as it would be a native drag and drop
      operation on the host OS.
    </para>

    <para>
      At the moment drag and drop is implemented for Windows-based and
      X-Windows-based systems, both on the host and guest side. As
      X-Windows supports many different drag and drop protocols only the
      most common one, XDND, is supported for now. Applications using
      other protocols, such as Motif or OffiX, will not be recognized by
      VirtualBox.
    </para>

    <para>
      In the context of using drag and drop, the origin of the data is
      called the <emphasis>source</emphasis>. That is, where the actual
      data comes from and is specified. The <emphasis>target</emphasis>
      specifies where the data from the source should go to.
      Transferring data from the source to the target can be done in
      various ways, such as copying, moving, or linking.

      <footnote>

        <para>
          At the moment only copying of data is supported. Moving or
          linking is not yet implemented.
        </para>

      </footnote>
    </para>

    <para>
      When transferring data from the host to the guest OS, the host in
      this case is the source, whereas the guest OS is the target.
      However, when transferring data from the guest OS to the host, the
      guest OS this time became the source and the host is the target.
    </para>

    <para>
      For security reasons drag and drop can be configured at runtime on
      a per-VM basis either using the <emphasis role="bold">Drag and
      Drop</emphasis> menu item in the "Devices" menu of the virtual
      machine or VBoxManage. The following modes are available:
    </para>

    <para>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/dnd-modes.png"
                   width="10cm" />
        </imageobject>
      </mediaobject>
    </para>

    <itemizedlist>

      <listitem>
        <para>
          <emphasis role="bold">Disabled.</emphasis> Disables the drag
          and drop feature entirely. This is the default when creating
          new VMs.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Host To Guest.</emphasis> Enables drag
          and drop operations from the host to the guest only.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Guest To Host.</emphasis> Enables drag
          and drop operations from the guest to the host only.
        </para>
      </listitem>

      <listitem>
        <para>
          <emphasis role="bold">Bidirectional.</emphasis> Enables drag
          and drop operations in both directions. From from the host to
          the guest, and from the guest to the host.
        </para>
      </listitem>

    </itemizedlist>

    <note>
      <para>
        Drag and drop support depends on the frontend being used. At the
        moment, only the VirtualBox Manager frontend provides this
        functionality.
      </para>
    </note>

    <para>
      To use VBoxManage for controlling the current drag and drop mode,
      see <xref
    linkend="vboxmanage" />. The commands
      <computeroutput>modifyvm</computeroutput> and
      <computeroutput>controlvm</computeroutput> allow setting of the
      VM's current drag and drop mode via the command line.
    </para>

    <sect2 id="guestadd-dnd-formats">

      <title>Supported Formats</title>

      <para>
        As VirtualBox can run on a variety of host operating systems and
        also supports a wide range of guests, certain data formats must
        be translated after transfer. This is so that the target
        operating system, which receiving the data, is able to handle
        them in an appropriate manner.
      </para>

      <note>
        <para>
          When dragging files no data conversion is done in any way. For
          example, when transferring a file from a Linux guest to a
          Windows host the Linux-specific line endings are not converted
          to Windows line endings.
        </para>
      </note>

      <para>
        The following formats are handled by the VirtualBox drag and
        drop service:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Plain text:</emphasis> From
            applications such as text editors, internet browsers and
            terminal windows.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Files:</emphasis> From file managers
            such as Windows Explorer, Nautilus, and Finder.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Directories:</emphasis> For
            directories, the same formats apply as for files.
          </para>
        </listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="guestadd-dnd-limitations">

      <title>Known Limitations</title>

      <para>
        The following limitations are known for drag and drop:
      </para>

      <para>
        On Windows hosts, dragging and dropping content between
        UAC-elevated (User Account Control) programs and
        non-UAC-elevated programs is not allowed. If you start
        VirtualBox with Administrator privileges then drag and drop will
        not work with Windows Explorer, which runs with regular user
        privileges by default.
      </para>

    </sect2>

  </sect1>

  <sect1 id="guestadd-video">

    <title>Hardware-Accelerated Graphics</title>

    <sect2 id="guestadd-3d">

      <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title>

      <para>
        The VirtualBox Guest Additions contain experimental hardware 3D
        support for Windows, Linux, and Solaris guests.

        <footnote>

          <para>
            OpenGL support for Windows guests was added with VirtualBox
            2.1; support for Linux and Solaris followed with VirtualBox
            2.2. With VirtualBox 3.0, Direct3D 8/9 support was added for
            Windows guests. OpenGL 2.0 is now supported as well. With
            VirtualBox 4.1 Windows Aero theme support is added for
            Windows Vista and Windows 7 guests (experimental)
          </para>

        </footnote>
      </para>

      <para>
        With this feature, if an application inside your virtual machine
        uses 3D features through the OpenGL or Direct3D 8/9 programming
        interfaces, instead of emulating them in software, which would
        be slow, VirtualBox will attempt to use your host's 3D hardware.
        This works for all supported host platforms, provided that your
        host operating system can make use of your accelerated 3D
        hardware in the first place.
      </para>

      <para>
        The 3D acceleration feature currently has the following
        preconditions:
      </para>

      <orderedlist>

        <listitem>
          <para>
            It is only available for certain Windows, Linux, and Solaris
            guests. In particular:
          </para>

          <itemizedlist>

            <listitem>
              <para>
                3D acceleration with Windows guests requires Windows
                2000, Windows XP, Vista or Windows 7. Both OpenGL and
                Direct3D 8/9 (not with Windows 2000) are supported
                (experimental).
              </para>
            </listitem>

            <listitem>
              <para>
                OpenGL on Linux requires kernel 2.6.27 and higher as
                well as X.org server version 1.5 and higher. Ubuntu
                10.10 and Fedora 14 have been tested and confirmed as
                working.
              </para>
            </listitem>

            <listitem>
              <para>
                OpenGL on Solaris guests requires X.org server version
                1.5 and higher.
              </para>
            </listitem>

          </itemizedlist>
        </listitem>

        <listitem>
          <para>
            The Guest Additions must be installed.
          </para>

          <note>
            <para>
              For the basic Direct3D acceleration to work in a Windows
              Guest, VirtualBox needs to replace Windows system files in
              the virtual machine. As a result, the Guest Additions
              installation program offers Direct3D acceleration as an
              option that must be explicitly enabled. Also, you must
              install the Guest Additions in Safe Mode. This does
              <emphasis>not</emphasis> apply to the WDDM Direct3D video
              driver available for Vista and higher. See
              <xref linkend="KnownIssues" /> for details.
            </para>
          </note>
        </listitem>

        <listitem>
          <para>
            Because 3D support is still experimental at this time, it is
            disabled by default and must be <emphasis>manually
            enabled</emphasis> in the VM settings. See
            <xref
            linkend="generalsettings" />.
          </para>

          <note>
            <para>
              Untrusted guest systems should not be allowed to use
              VirtualBox's 3D acceleration features, just as untrusted
              host software should not be allowed to use 3D
              acceleration. Drivers for 3D hardware are generally too
              complex to be made properly secure and any software which
              is allowed to access them may be able to compromise the
              operating system running them. In addition, enabling 3D
              acceleration gives the guest direct access to a large body
              of additional program code in the VirtualBox host process
              which it might conceivably be able to use to crash the
              virtual machine.
            </para>
          </note>
        </listitem>

      </orderedlist>

      <para>
        To enable Aero theme support, the VirtualBox WDDM video driver
        must be installed, which is available with the Guest Additions
        installation. The WDDM driver is not installed by default for
        Vista and Windows 7 guest and must be <emphasis>manually
        selected</emphasis> in the Guest Additions installer by clicking
        <emphasis role="bold">No</emphasis> in the
        <emphasis role="bold">Would You Like to Install Basic Direct3D
        Support</emphasis> dialog displayed when the Direct3D feature is
        selected.
      </para>

      <para>
        The Aero theme is not enabled by default. To enable it, do the
        following:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            <emphasis role="bold">Windows Vista guests:</emphasis>
            Right-click on the desktop and select
            <emphasis role="bold">Personalize</emphasis>, then select
            <emphasis role="bold">Windows Color and
            Appearance</emphasis> in the Personalization window. In the
            Appearance Settings dialog, select
            <emphasis role="bold">Windows Aero</emphasis> and click
            <emphasis role="bold">OK</emphasis>.
          </para>
        </listitem>

        <listitem>
          <para>
            <emphasis role="bold">Windows 7 guests:</emphasis>
            Right-click on the desktop and select
            <emphasis role="bold">Personalize</emphasis>. Select any
            Aero theme in the Personalization window.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        Technically, VirtualBox implements this by installing an
        additional hardware 3D driver inside your guest when the Guest
        Additions are installed. This driver acts as a hardware 3D
        driver and reports to the guest operating system that the
        (virtual) hardware is capable of 3D hardware acceleration. When
        an application in the guest then requests hardware acceleration
        through the OpenGL or Direct3D programming interfaces, these are
        sent to the host through a special communication tunnel
        implemented by VirtualBox, and then the
        <emphasis>host</emphasis> performs the requested 3D operation
        via the host's programming interfaces.
      </para>

    </sect2>

    <sect2 id="guestadd-2d">

      <title>Hardware 2D Video Acceleration for Windows Guests</title>

      <para>
        Starting with version 3.1, the VirtualBox Guest Additions
        contain experimental hardware 2D video acceleration support for
        Windows guests.
      </para>

      <para>
        With this feature, if an application such as a video player
        inside your Windows VM uses 2D video overlays to play a movie
        clip, then VirtualBox will attempt to use your host's video
        acceleration hardware instead of performing overlay stretching
        and color conversion in software, which would be slow. This
        currently works for Windows, Linux and Mac host platforms,
        provided that your host operating system can make use of 2D
        video acceleration in the first place.
      </para>

      <para>
        Hardware 2D video acceleration currently has the following
        preconditions:
      </para>

      <orderedlist>

        <listitem>
          <para>
            Only available for Windows guests (XP or later).
          </para>
        </listitem>

        <listitem>
          <para>
            Guest Additions must be installed.
          </para>
        </listitem>

        <listitem>
          <para>
            Because 2D support is still experimental at this time, it is
            disabled by default and must be <emphasis>manually
            enabled</emphasis> in the VM settings. See
            <xref
            linkend="generalsettings" />.
          </para>
        </listitem>

      </orderedlist>

      <para>
        Technically, VirtualBox implements this by exposing video
        overlay DirectDraw capabilities in the Guest Additions video
        driver. The driver sends all overlay commands to the host
        through a special communication tunnel implemented by
        VirtualBox. On the host side, OpenGL is then used to implement
        color space transformation and scaling
      </para>

    </sect2>

  </sect1>

  <sect1 id="seamlesswindows">

    <title>Seamless Windows</title>

    <para>
      With the <emphasis>seamless windows</emphasis> feature of
      VirtualBox, you can have the windows that are displayed within a
      virtual machine appear side by side next to the windows of your
      host. This feature is supported for the following guest operating
      systems, provided that the Guest Additions are installed:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          Windows guests (support added with VirtualBox 1.5)
        </para>
      </listitem>

      <listitem>
        <para>
          Supported Linux or Solaris guests running the X Window System
          (added with VirtualBox 1.6)
        </para>
      </listitem>

    </itemizedlist>

    <para>
      After seamless windows are enabled, VirtualBox suppresses the
      display of the desktop background of your guest, allowing you to
      run the windows of your guest operating system seamlessly next to
      the windows of your host.
    </para>

    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="images/seamless.png" width="14cm" />
      </imageobject>
    </mediaobject>

    <para>
      To enable seamless mode, after starting the virtual machine, press
      the <emphasis role="bold">Host key + L</emphasis>. The Host key is
      normally the right control key. This will enlarge the size of the
      VM's display to the size of your host screen and mask out the
      guest operating system's background. To disable seamless windows
      and go back to the normal VM display, press the Host key + L
      again.
    </para>

  </sect1>

  <sect1 id="guestadd-guestprops">

    <title>Guest Properties</title>

    <para>
      Starting with version 2.1, VirtualBox enables requesting of
      certain properties from a running guest, provided that the
      VirtualBox Guest Additions are installed and the VM is running.
      This provides the following advantages:
    </para>

    <itemizedlist>

      <listitem>
        <para>
          A number of predefined VM characteristics are automatically
          maintained by VirtualBox and can be retrieved on the host. For
          example, to monitor VM performance and statistics.
        </para>
      </listitem>

      <listitem>
        <para>
          Arbitrary string data can be exchanged between guest and host.
          This works in both directions.
        </para>
      </listitem>

    </itemizedlist>

    <para>
      To accomplish this, VirtualBox establishes a private communication
      channel between the VirtualBox Guest Additions and the host, and
      software on both sides can use this channel to exchange string
      data for arbitrary purposes. Guest properties are simply string
      keys to which a value is attached. They can be set, or written to,
      by either the host and the guest. They can also be read from both
      sides.
    </para>

    <para>
      In addition to establishing the general mechanism of reading and
      writing values, a set of predefined guest properties is
      automatically maintained by the VirtualBox Guest Additions to
      allow for retrieving interesting guest data such as the guest's
      exact operating system and service pack level, the installed
      version of the Guest Additions, users that are currently logged
      into the guest OS, network statistics and more. These predefined
      properties are all prefixed with
      <computeroutput>/VirtualBox/</computeroutput> and organized into a
      hierarchical tree of keys.
    </para>

    <para>
      Some of this runtime information is shown when you select
      <emphasis role="bold">Session Information Dialog</emphasis> from a
      virtual machine's Machine menu.
    </para>

    <para>
      A more flexible way to use this channel is via the
      <computeroutput>VBoxManage guestproperty</computeroutput> command.
      See <xref linkend="vboxmanage-guestproperty" />. For example, to
      have <emphasis>all</emphasis> the available guest properties for a
      given running VM listed with their respective values, use this
      command:
    </para>

<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
(C) 2005-2018 Oracle Corporation
All rights reserved.

Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
    timestamp: 1229098278843087000, flags:
Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
    timestamp: 1229098278950553000, flags:
Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
    timestamp: 1229098279122627000, flags:
Name: /VirtualBox/GuestAdd/InstallDir,
    value: C:/Program Files/Oracle/VirtualBox
    Guest Additions, timestamp: 1229098279269739000, flags:
Name: /VirtualBox/GuestAdd/Revision, value: 40720,
    timestamp: 1229098279345664000, flags:
Name: /VirtualBox/GuestAdd/Version, value: <replaceable>version-number</replaceable>,
    timestamp: 1229098279479515000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279651731000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279804835000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279880611000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279882618000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279883195000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279885027000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279886838000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279890600000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279893056000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720,
    timestamp: 1229098279895767000, flags:
Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
    timestamp: 1229099826317660000, flags:
Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
    timestamp: 1229098455580553000, flags:
Name: /VirtualBox/GuestInfo/Net/Count, value: 1,
    timestamp: 1229099826299785000, flags:
Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
    timestamp: 1229098151272771000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
    timestamp: 1229099826300088000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
    timestamp: 1229099826300220000, flags:
Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
    timestamp: 1229099826300350000, flags:
Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
    timestamp: 1229099826300524000, flags:
Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
    timestamp: 1229099826317386000, flags:</screen>

    <para>
      To query the value of a single property, use the
      <computeroutput>get</computeroutput> subcommand as follows:
    </para>

<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
(C) 2005-2018 Oracle Corporation
All rights reserved.

Value: Windows Vista Business Edition</screen>

    <para>
      To add or change guest properties from the guest, use the tool
      <computeroutput>VBoxControl</computeroutput>. This tool is
      included in the Guest Additions of VirtualBox 2.2 or later. When
      started from a Linux guest, this tool requires root privileges for
      security reasons:
    </para>

<screen>$ sudo VBoxControl guestproperty enumerate
VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable>
(C) 2005-2018 Oracle Corporation
All rights reserved.

Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
    timestamp: 1265813265835667000, flags: &lt;NULL&gt;
Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
    timestamp: 1265813265836305000, flags: &lt;NULL&gt;
      ...</screen>

    <para>
      For more complex needs, you can use the VirtualBox programming
      interfaces. See <xref linkend="VirtualBoxAPI" />.
    </para>

  </sect1>

  <sect1 id="guestadd-guestcontrol">

    <title>Guest Control</title>

    <para>
      Starting with version 3.2, the Guest Additions of VirtualBox allow
      starting applications inside a VM from the host system.
    </para>

    <para>
      For this to work, the application needs to be installed inside the
      guest. No additional software needs to be installed on the host.
      Additionally, text mode output to stdout and stderr can be shown
      on the host for further processing. There are options to specify
      user credentials and a timeout value, in milliseconds, to limit
      the time the application is able to run.
    </para>

    <para>
      This feature can be used to automate deployment of software within
      the guest.
    </para>

    <para>
      Starting with version 4.0, the Guest Additions for Windows allow
      for automatic updating. This applies for already installed Guest
      Additions version 4.0 or later. Also, copying files from host to
      the guest as well as remotely creating guest directories is
      available.
    </para>

    <para>
      To use these features, use the VirtualBox command line. See
      <xref
    linkend="vboxmanage-guestcontrol" />.
    </para>

  </sect1>

  <sect1 id="guestadd-memory-usage">

    <title>Memory Overcommitment</title>

    <para>
      In server environments with many VMs, the Guest Additions can be
      used to share physical host memory between several VMs. This
      reduces the total amount of memory in use by the VMs. If memory
      usage is the limiting factor and CPU resources are still
      available, this can help with running more VMs on each host.
    </para>

    <sect2 id="guestadd-balloon">

      <title>Memory Ballooning</title>

      <para>
        Starting with version 3.2, the Guest Additions of VirtualBox can
        change the amount of host memory that a VM uses while the
        machine is running. Because of how this is implemented, this
        feature is called <emphasis>memory ballooning</emphasis>.
      </para>

      <note>
        <itemizedlist>

          <listitem>
            <para>
              VirtualBox supports memory ballooning only on 64-bit
              hosts. It is not supported on Mac OS X hosts.
            </para>
          </listitem>

          <listitem>
            <para>
              Memory ballooning does not work with large pages enabled.
              To turn off large pages support for a VM, run
              <computeroutput>VBoxManage modifyvm &lt;VM name&gt;
              --largepages off</computeroutput>
            </para>
          </listitem>

        </itemizedlist>
      </note>

      <para>
        Normally, to change the amount of memory allocated to a virtual
        machine, you have to shut down the virtual machine entirely and
        modify its settings. With memory ballooning, memory that was
        allocated for a virtual machine can be given to another virtual
        machine without having to shut the machine down.
      </para>

      <para>
        When memory ballooning is requested, the VirtualBox Guest
        Additions, which run inside the guest, allocate physical memory
        from the guest operating system on the kernel level and lock
        this memory down in the guest. This ensures that the guest will
        not use that memory any longer. No guest applications can
        allocate it, and the guest kernel will not use it either.
        VirtualBox can then reuse this memory and give it to another
        virtual machine.
      </para>

      <para>
        The memory made available through the ballooning mechanism is
        only available for reuse by VirtualBox. It is
        <emphasis>not</emphasis> returned as free memory to the host.
        Requesting balloon memory from a running guest will therefore
        not increase the amount of free, unallocated memory on the host.
        Effectively, memory ballooning is therefore a memory
        overcommitment mechanism for multiple virtual machines while
        they are running. This can be useful to temporarily start
        another machine, or in more complicated environments, for
        sophisticated memory management of many virtual machines that
        may be running in parallel depending on how memory is used by
        the guests.
      </para>

      <para>
        At this time, memory ballooning is only supported through
        VBoxManage. Use the following command to increase or decrease
        the size of the memory balloon within a running virtual machine
        that has Guest Additions installed:
      </para>

<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen>

      <para>
        where <replaceable>VM name</replaceable> is the name or UUID of
        the virtual machine in question and <replaceable>n</replaceable>
        is the amount of memory to allocate from the guest in megabytes.
        See <xref
      linkend="vboxmanage-controlvm" />.
      </para>

      <para>
        You can also set a default balloon that will automatically be
        requested from the VM every time after it has started up with
        the following command:

<screen>VBoxManage modifyvm "VM name" --guestmemoryballoon n</screen>
      </para>

      <para>
        By default, no balloon memory is allocated. This is a VM
        setting, like other <computeroutput>modifyvm</computeroutput>
        settings, and therefore can only be set while the machine is
        shut down. See <xref
      linkend="vboxmanage-modifyvm" />.
      </para>

    </sect2>

    <sect2 id="guestadd-pagefusion">

      <title>Page Fusion</title>

      <para>
        Whereas memory ballooning simply reduces the amount of RAM that
        is available to a VM, Page Fusion works differently. It avoids
        memory duplication between several similar running VMs.
      </para>

      <para>
        In a server environment running several similar VMs, for example
        with identical operating systems, on the same host, lots of
        memory pages are identical. VirtualBox's Page Fusion technology,
        introduced with VirtualBox 3.2, is a novel technique to
        efficiently identify these identical memory pages and share them
        between multiple VMs.
      </para>

      <note>
        <para>
          VirtualBox supports Page Fusion only on 64-bit hosts, and it
          is not supported on Mac OS X hosts. Page Fusion currently
          works only with Windows 2000 and later guests.
        </para>
      </note>

      <para>
        The more similar the VMs on a given host are, the more
        efficiently Page Fusion can reduce the amount of host memory
        that is in use. It therefore works best if all VMs on a host run
        identical operating systems, such as Windows XP Service Pack 2.
        Instead of having a complete copy of each operating system in
        each VM, Page Fusion identifies the identical memory pages in
        use by these operating systems and eliminates the duplicates,
        sharing host memory between several machines. This is called
        <emphasis>deduplication</emphasis>. If a VM tries to modify a
        page that has been shared with other VMs, a new page is
        allocated again for that VM with a copy of the shared page. This
        is called <emphasis>copy on write</emphasis>. All this is fully
        transparent to the virtual machine.
      </para>

      <para>
        You may be familiar with this kind of memory overcommitment from
        other hypervisor products, which call this feature
        <emphasis>page sharing</emphasis> or <emphasis>same page
        merging</emphasis>. However, Page Fusion differs significantly
        from those other solutions, whose approaches have several
        drawbacks:
      </para>

      <itemizedlist>

        <listitem>
          <para>
            Traditional hypervisors scan <emphasis>all</emphasis> guest
            memory and compute checksums (hashes) for every single
            memory page. Then, they look for pages with identical hashes
            and compare the entire content of those pages. If two pages
            produce the same hash, it is very likely that the pages are
            identical in content. This process can take rather long,
            especially if the system is not idling. As a result, the
            additional memory only becomes available after a significant
            amount of time, such as hours or sometimes days. Even worse,
            this kind of page sharing algorithm generally consumes
            significant CPU resources and increases the virtualization
            overhead by 10 to 20%.
          </para>

          <para>
            Page Fusion in VirtualBox uses logic in the VirtualBox Guest
            Additions to quickly identify memory cells that are most
            likely identical across VMs. It can therefore achieve most
            of the possible savings of page sharing almost immediately
            and with almost no overhead.
          </para>
        </listitem>

        <listitem>
          <para>
            Page Fusion is also much less likely to be confused by
            identical memory that it will eliminate, just to learn
            seconds later that the memory will now change and having to
            perform a highly expensive and often service-disrupting
            reallocation.
          </para>
        </listitem>

      </itemizedlist>

      <para>
        At this time, Page Fusion can only be controlled with
        VBoxManage, and only while a VM is shut down. To enable Page
        Fusion for a VM, use the following command:
      </para>

<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen>

      <para>
        You can observe Page Fusion operation using some metrics.
        <computeroutput>RAM/VMM/Shared</computeroutput> shows the total
        amount of fused pages, whereas the per-VM metric
        <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will
        return the amount of fused memory for a given VM. See
        <xref
        linkend="vboxmanage-metrics" /> for information on
        how to query metrics.
      </para>

      <note>
        <para>
          Enabling Page Fusion might indirectly increase the chances for
          malicious guests to successfully attack other VMs running on
          the same host. See <xref linkend="pot-insecure"/>.
        </para>
      </note>

    </sect2>

  </sect1>

</chapter>