user_GuestAdditions.xml revision f9aab99c9045e0f7688b2e98e1deb3062bdf467b
9655fcecf0e74ce9fdc5650b29fc8363b9877ba5vboxsync<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync <para>The previous chapter covered getting started with VirtualBox and
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync installing operating systems in a virtual machine. For any serious and
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync interactive use, the VirtualBox Guest Additions will make your life much
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync easier by providing closer integration between host and guest and improving
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync the interactive performance of guest systems. This chapter describes the
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync Guest Additions in detail.</para>
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync <para>As mentioned in <xref linkend="virtintro" />, the Guest Additions
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync are designed to be installed <emphasis>inside</emphasis> a virtual machine
818084e1868c57ef296e0fc5622e474e63ec4be0vboxsync after the guest operating system has been installed. They consist of
818084e1868c57ef296e0fc5622e474e63ec4be0vboxsync device drivers and system applications that optimize the guest operating
818084e1868c57ef296e0fc5622e474e63ec4be0vboxsync system for better performance and usability. Please see <xref
818084e1868c57ef296e0fc5622e474e63ec4be0vboxsync linkend="guestossupport" /> for details on what guest operating systems
d4c0b01d95e56701ccb5a430fea1a36dc671153bvboxsync are fully supported with Guest Additions by VirtualBox.</para>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <para>The VirtualBox Guest Additions for all supported guest operating
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync systems are provided as a single CD-ROM image file which is called
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This image file
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync is located in the installation directory of VirtualBox. To install the
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync Guest Additions for a particular VM, you mount this ISO file in your VM as
d4c0b01d95e56701ccb5a430fea1a36dc671153bvboxsync a virtual CD-ROM and install from there.</para>
af7209255033c3b77816f81ef6293ff8070ee156vboxsync <para>The Guest Additions offer the following features:<glosslist>
af7209255033c3b77816f81ef6293ff8070ee156vboxsync <glossentry>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>To overcome the limitations for mouse support that were
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync described in <xref linkend="keyb_mouse_normal" />, this provides
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync you with seamless mouse support. You will only have one mouse
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync pointer and pressing the Host key is no longer required to "free"
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync the mouse from being captured by the guest OS. To make this work,
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync a special mouse driver is installed in the guest that communicates
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync with the "real" mouse driver on your host and moves the guest
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync mouse pointer accordingly.</para>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </glossdef>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </glossentry>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <glossentry>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>These provide an easy way to exchange files between the host
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync and the guest. Much like ordinary Windows network shares, you can
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync tell VirtualBox to treat a certain host directory as a shared
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync folder, and VirtualBox will make it available to the guest
23ed8fa7774a8cd3defa40b71ead21f51391c11fvboxsync operating system as a network share, irrespective of whether guest
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync actually has a network. For details, please refer to <xref
8af51386c2aa6a8411193dc96c79cbef7dd8f2d1vboxsync </glossdef>
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync </glossentry>
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync <glossentry>
7971d68750815895622e31b4c1a86913dd58810evboxsync <para>While the virtual graphics card which VirtualBox emulates
7971d68750815895622e31b4c1a86913dd58810evboxsync for any guest operating system provides all the basic features,
183bc517a9dca5a54ba6701581066363e78de360vboxsync the custom video drivers that are installed with the Guest
183bc517a9dca5a54ba6701581066363e78de360vboxsync Additions provide you with extra high and non-standard video modes
183bc517a9dca5a54ba6701581066363e78de360vboxsync as well as accelerated video performance.</para>
183bc517a9dca5a54ba6701581066363e78de360vboxsync <para>In addition, with Windows, Linux and Solaris guests, you can
183bc517a9dca5a54ba6701581066363e78de360vboxsync resize the virtual machine's window if the Guest Additions are
183bc517a9dca5a54ba6701581066363e78de360vboxsync installed. The video resolution in the guest will be automatically
183bc517a9dca5a54ba6701581066363e78de360vboxsync adjusted (as if you had manually entered an arbitrary resolution
183bc517a9dca5a54ba6701581066363e78de360vboxsync in the guest's display settings). Please see <xref
d58eb7078d9ec144995e35f4647f6ca6c39c9f32vboxsync <para>Finally, if the Guest Additions are installed, 3D graphics
d58eb7078d9ec144995e35f4647f6ca6c39c9f32vboxsync and 2D video for guest applications can be accelerated; see <xref
d58eb7078d9ec144995e35f4647f6ca6c39c9f32vboxsync </glossdef>
d58eb7078d9ec144995e35f4647f6ca6c39c9f32vboxsync </glossentry>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <glossentry>
b7a585d31721824bf5410df05253b6466f768351vboxsync <para>With this feature, the individual windows that are displayed
4a975e177b1b727641d72b662f388fb72116fd56vboxsync on the desktop of the virtual machine can be mapped on the host's
4a975e177b1b727641d72b662f388fb72116fd56vboxsync desktop, as if the underlying application was actually running on
b7a585d31721824bf5410df05253b6466f768351vboxsync the host. See <xref linkend="seamlesswindows" /> for
b7a585d31721824bf5410df05253b6466f768351vboxsync details.</para>
8bfe66cdf44bdbbf326f0716e7af59809db4f53dvboxsync </glossdef>
2f57ee9072f1e08bf2289054ae226559500e5781vboxsync </glossentry>
2f57ee9072f1e08bf2289054ae226559500e5781vboxsync <glossentry>
2f57ee9072f1e08bf2289054ae226559500e5781vboxsync <glossterm>Generic host/guest communication channels</glossterm>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <para>The Guest Additions enable you to control and monitor guest
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync execution in ways other than those mentioned above. The so-called
d13746bffe2c3ae67693c00b13f5f86aa4a5929fvboxsync "guest properties" provide a generic string-based mechanism to
d13746bffe2c3ae67693c00b13f5f86aa4a5929fvboxsync exchange data bits between a guest and a host, some of which have
d13746bffe2c3ae67693c00b13f5f86aa4a5929fvboxsync special meanings for controlling and monitoring the guest; see
d13746bffe2c3ae67693c00b13f5f86aa4a5929fvboxsync <xref linkend="guestadd-guestprops" /> for details.</para>
dbec430110b1ef6ff49d5c6019063287f7764733vboxsync <para>Additionally, applications can be started in a guest from
dbec430110b1ef6ff49d5c6019063287f7764733vboxsync the host; see <xref linkend="guestadd-guestcontrol" />.</para>
dbec430110b1ef6ff49d5c6019063287f7764733vboxsync </glossdef>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync </glossentry>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <glossentry>
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync <para>With the Guest Additions installed, VirtualBox can ensure
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync that the guest's system time is better synchronized with that of
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync the host.</para>
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync <para>For various reasons, the time in the guest might run at a
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync slightly different rate than the time on the host. The host could
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync be receiving updates via NTP and its own time might not run
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync linearly. A VM could also be paused, which stops the flow of time
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync in the guest for a shorter or longer period of time. When the wall
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync clock time between the guest and host only differs slightly, the
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync time synchronization service attempts to gradually and smoothly
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync adjust the guest time in small increments to either "catch up" or
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync "lose" time. When the difference is too great (e.g., a VM paused
ea1d71e98cc2fa2685d53baac1ca8baf78152a96vboxsync for hours or restored from saved state), the guest time is changed
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync immediately, without a gradual adjustment.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>The Guest Additions will re-synchronize the time regularly.
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync See <xref linkend="changetimesync" /> for how to configure the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync parameters of the time synchronization mechanism.</para>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync </glossdef>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync </glossentry>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <glossentry>
b2a388b556828f96c87a5df80ab54e24107ade32vboxsync <para>With the Guest Additions installed, the clipboard of the
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync guest operating system can optionally be shared with your host
818084e1868c57ef296e0fc5622e474e63ec4be0vboxsync operating system; see <xref linkend="generalsettings" />.</para>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync </glossdef>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync </glossentry>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync <glossentry>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync <glossterm>Automated logons (credentials passing)</glossterm>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync <para>For details, please see <xref linkend="autologon" />.</para>
0f08eac589947ea8c8abcd6d340704eaa6efcad9vboxsync </glossdef>
11018549d519a09500d83983867b93d03c7422bfvboxsync </glossentry>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>Each version of VirtualBox, even minor releases, ship with their own
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync version of the Guest Additions. While the interfaces through which the
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync VirtualBox core communicates with the Guest Additions are kept stable so
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync that Guest Additions already installed in a VM should continue to work
9d8e19f1b1cdb751fe52a10755ae65870fe5ee80vboxsync when VirtualBox is upgraded on the host, for best results, it is
a89bd5bcd9aba1ea74ec3b0e010e63fbb888441fvboxsync recommended to keep the Guest Additions at the same version.</para>
9d8e19f1b1cdb751fe52a10755ae65870fe5ee80vboxsync <para>Starting with VirtualBox 3.1, the Windows and Linux Guest Additions
9d8e19f1b1cdb751fe52a10755ae65870fe5ee80vboxsync therefore check automatically whether they have to be updated. If the host
bfeb98d857924e4f8388daf457fadfcac539829bvboxsync is running a newer VirtualBox version than the Guest Additions, a
bfeb98d857924e4f8388daf457fadfcac539829bvboxsync notification with further instructions is displayed in the guest.</para>
bfeb98d857924e4f8388daf457fadfcac539829bvboxsync <para>To disable this update check for the Guest Additions of a given
bfeb98d857924e4f8388daf457fadfcac539829bvboxsync virtual machine, set the value of its
bfeb98d857924e4f8388daf457fadfcac539829bvboxsync <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync guest property to <computeroutput>0</computeroutput>; see <xref
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync linkend="guestadd-guestprops" /> for details.</para>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <title>Installing and Maintaining Guest Additions</title>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <para>Guest Additions are available for virtual machines running Windows,
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync Linux, Solaris or OS/2. The following sections describe the specifics of
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync each variant in detail.</para>
777ebbcbb40cb4adcbe9fa86bdbe92d2cd2c1ba3vboxsync <para>The VirtualBox Windows Guest Additions are designed to be
777ebbcbb40cb4adcbe9fa86bdbe92d2cd2c1ba3vboxsync installed in a virtual machine running a Windows operating system. The
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync following versions of Windows guests are supported:</para>
0efe7a330b5ccd21bd18cacbc84477bcd42eeeb1vboxsync <itemizedlist>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>Microsoft Windows NT 4.0 (any service pack)</para>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </listitem>
557a15daf14d2854920c989acb899f43ed8d0d15vboxsync <para>Microsoft Windows 2000 (any service pack)</para>
557a15daf14d2854920c989acb899f43ed8d0d15vboxsync </listitem>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>Microsoft Windows XP (any service pack)</para>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </listitem>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <para>Microsoft Windows Server 2003 (any service pack)</para>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </listitem>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync </listitem>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>Microsoft Windows Vista (all editions)</para>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync </listitem>
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync </listitem>
81de4fbf81465a07672c32cfaeb0b5fcfebbebc5vboxsync </itemizedlist>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>In the "Devices" menu in the virtual machine's menu bar,
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync VirtualBox has a handy menu item named "Install guest additions",
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync which mounts the Guest Additions ISO file inside your virtual machine.
327375235a36287ca25b77811f51b970c87f8976vboxsync A Windows guest should then automatically start the Guest Additions
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync installer, which installs the Guest Additions into your Windows
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync guest.</para>
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync <para>For the basic Direct3D acceleration to work in a Windows Guest, you
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync have to install the Guest Additions in "Safe Mode".
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync This does <emphasis role="bold">not</emphasis> apply to the experimental
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync WDDM Direct3D video driver available
11018549d519a09500d83983867b93d03c7422bfvboxsync for Vista and Windows 7 guests, see <xref linkend="KnownIssues" /> for
373eeb2935f4cf306f2f8d5c94c29d37ef2f30aevboxsync details.<footnote><para>The experimental WDDM driver was added with
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync <para>If you prefer to mount the additions manually, you can perform
b6781f793421df3a184eb7d195555e95fcf20943vboxsync the following steps:</para>
b6781f793421df3a184eb7d195555e95fcf20943vboxsync <orderedlist>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Start the virtual machine in which you have installed
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync Windows.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Select "Mount CD/DVD-ROM" from the "Devices" menu in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync virtual machine's menu bar and then "CD/DVD-ROM image". This
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync brings up the Virtual Media Manager described in <xref
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>In the Virtual Media Manager, press the "Add" button and
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync browse your host file system for the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>VBoxGuestAdditions.iso</computeroutput>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync file:<itemizedlist>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>On a Windows host, you can find this file in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync VirtualBox installation directory (usually under
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>C:\Program
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>On Mac OS X hosts, you can find this file in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync application bundle of VirtualBox. (Right click on the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync VirtualBox icon in Finder and choose <emphasis>Show Package
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync Contents</emphasis>. There it is located in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync folder.)</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>On a Linux host, you can find this file in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>additions</computeroutput> folder under
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync where you installed VirtualBox (normally
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>/opt/VirtualBox/</computeroutput>).</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>On Solaris hosts, you can find this file in the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>additions</computeroutput> folder under
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync where you installed VirtualBox (normally
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>/opt/VirtualBox</computeroutput>).</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Back in the Virtual Media Manager, select that ISO file and
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync press the "Select" button. This will mount the ISO file and
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync present it to your Windows guest as a CD-ROM.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </orderedlist>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Unless you have the Autostart feature disabled in your Windows
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync guest, Windows will now autostart the VirtualBox Guest Additions
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync installation program from the Additions ISO. If the Autostart feature
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync has been turned off, choose
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync CD/DVD drive inside the guest to start the installer.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>The installer will add several device drivers to the Windows
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync driver database and then invoke the hardware detection wizard.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Depending on your configuration, it might display warnings that
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync the drivers are not digitally signed. You must confirm these in order
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync to continue the installation and properly install the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync Additions.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>After installation, reboot your guest operating system to
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync activate the Additions.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <title>Updating the Windows Guest Additions</title>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Windows Guest Additions can be updated by running the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync installation program again, as previously described. This will then
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync replace the previous Additions drivers with updated versions.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Alternatively, you may also open the Windows Device Manager and
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync select "Update driver..." for two devices:</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <orderedlist>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </orderedlist>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>For each, choose to provide your own driver and use "Have Disk"
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync to point the wizard to the CD-ROM drive with the Guest
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync Additions.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>In order to allow for completely unattended guest installations,
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync you can specify a command line parameter to the install
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync launcher:</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>This automatically installs the right files and drivers for the
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync corresponding platform (32- or 64-bit).</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Because of the drivers are not yet WHQL certified, you still
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync might get some driver installation popups, depending on the Windows
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync guest version.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>For more options regarding unattended guest installations,
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync consult the command line help by using the command:</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>If you would like to install the files and drivers manually, you
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync can extract the files from the Windows Guest Additions setup by
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync typing:</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>To explicitly extract the Windows Guest Additions for another
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync platform than the current running one (e.g. 64-bit files on a 32-bit
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync system), you have to execute the appropriate platform installer
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync (<computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput> or
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>) with
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync the <computeroutput>/extract</computeroutput> parameter.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync for Linux are a set of device drivers and system applications which may
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync be installed in the guest operating system.</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>The following Linux distributions are officially supported:</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <itemizedlist>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>Redhat Enterprise Linux as of version 3;</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync <para>SUSE and openSUSE Linux as of version 9;</para>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </listitem>
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync </itemizedlist>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Many other distributions are known to work with the Guest
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Additions.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>The version of the Linux kernel supplied by default in SUSE and
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 (server
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync edition) contains a bug which can cause it to crash during startup when
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync it is run in a virtual machine. The Guest Additions work in those
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync distributions.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Note that some Linux distributions already come with all or part of
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync the VirtualBox Guest Additions. You may choose to keep the distribution's
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync version of the Guest Additions but these are often not up to date and
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync limited in functionality, so we recommend replacing them with the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Guest Additions that come with VirtualBox. The VirtualBox Linux Guest
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Additions installer tries to detect existing installation and replace
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync them but depending on how the distribution integrates the Guest
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Additions, this may require some manual interaction. It is highly
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync recommended to take a snapshot of the virtual machine before replacing
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync pre-installed Guest Additions.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <title>Installing the Linux Guest Additions</title>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>The VirtualBox Guest Additions for Linux are provided on the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync same virtual CD-ROM file as the Guest Additions for Windows described
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync above. They also come with an installation program guiding you through
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync the setup process, although, due to the significant differences between
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Linux distributions, installation may be slightly more complex.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Installation generally involves the following steps:</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <orderedlist>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Before installing the Guest Additions, you will have to
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync prepare your guest system for building external kernel modules.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync This works similarly as described in <xref
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync linkend="externalkernelmodules" />, except that this step must now
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync be performed in your Linux <emphasis>guest</emphasis> instead of
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync on a Linux host system, as described there.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Again, as with Linux hosts, we recommend using DKMS if it is
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync available for the guest system. If it is not installed, use this
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync or for Fedora systems: <screen>yum install dkms</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Be sure to install DKMS <emphasis>before</emphasis>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync installing the Linux Guest Additions. If DKMS is not available
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync or not installed, the guest kernel modules will need to be
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync recreated manually whenever the guest kernel is updated using
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync the command <screen>/etc/init.d/vboxadd setup</screen> as root.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Insert the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD file
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync into your Linux guest's virtual CD-ROM drive, exactly the same way
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync as described for a Windows guest in <xref
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Change to the directory where your CD-ROM drive is mounted
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync and execute as root:</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </orderedlist>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>For your convenience, we provide the following step-by-step
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync instructions for freshly installed copies of recent versions of the most
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync popular Linux distributions. After these preparational steps, you can
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync execute the VirtualBox Guest Additions installer as described
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>apt-get update</screen> as root
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync followed by <screen>apt-get upgrade</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install DKMS using <screen>apt-get install dkms</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your guest system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates and then proceed as described above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>yum update</screen></para> as root.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install DKMS and the GNU C compiler using <screen>yum install dkms</screen>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync followed by <screen>yum install gcc</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your guest system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates and then proceed as described above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>zypper update</screen></para> as root.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install the make tool and the GNU C compiler using
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your guest system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Find out which kernel you are running using <screen>uname -a</screen>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync An example would be
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <computeroutput>2.6.31.12-0.2-default</computeroutput> which
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync refers to the "default" kernel. Then install the correct
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync kernel development package. In the above example this would be
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <screen>zypper install kernel-default-devel</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Make sure that your running kernel
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync (<computeroutput>uname -a</computeroutput>) and the kernel
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync packages you have installed (<computeroutput>rpm -qa
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync kernel\*</computeroutput>) have the exact same version number.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Proceed with the installation as described above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <title>SuSE Linux Enterprise Desktop (SLED)</title>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>zypper update</screen></para> as root.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install the GNU C compiler using <screen>zypper install gcc</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your guest system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Find out which kernel you are running using <screen>uname -a</screen>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync An example would be
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <computeroutput>2.6.27.19-5.1-default</computeroutput> which
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync refers to the "default" kernel. Then install the correct
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync kernel development package. In the above example this would be
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <screen>zypper install kernel-syms kernel-source</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Make sure that your running kernel
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync (<computeroutput>uname -a</computeroutput>) and the kernel
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync packages you have installed (<computeroutput>rpm -qa
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync kernel\*</computeroutput>) have the exact same version number.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Proceed with the installation as described above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Mandrake ships with the VirtualBox Guest Additions which
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync will be replaced if you follow these steps.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>urpmi --auto-update</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install DKMS using <screen>urpmi dkms</screen> and make
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync sure to choose the correct kernel-devel package when asked by
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync the installer (use <computeroutput>uname -a</computeroutput>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync to compare).</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <title>CentOS, Red Hat Enterprise Linux and Oracle
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync Enterprise Linux</title>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>For versions prior to 6, add <computeroutput>divider=10</computeroutput>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync to the kernel boot options in
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <computeroutput>/etc/grub.conf</computeroutput> to reduce the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync idle CPU load.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>yum update</screen></para> as root.
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install the GNU C compiler and the kernel development
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync packages using <screen>yum install gcc</screen> followed by
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Reboot your guest system in order to activate the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync updates and then proceed as described above.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In case Oracle Enterprise Linux does not find the
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync required packages, you either have to install them from a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync different source (e.g. DVD) or use Oracle's public Yum server
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync located at <ulink
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync url="http://public-yum.oracle.com/">http://public-yum.oracle.com</ulink>.</para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>In order to fully update your guest system, open a
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync terminal and run <screen>apt-get update</screen> as root
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync followed by <screen>apt-get upgrade</screen></para>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync </listitem>
d9a2b1593e3b64139f7ace4e7a5d9b4999efa630vboxsync <para>Install the make tool and the GNU C compiler using
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync </listitem>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Reboot your guest system in order to activate the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync updates.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync </listitem>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Determine the exact version of your kernel using
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <computeroutput>uname -a</computeroutput> and install the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync correct version of the linux-headers package, e.g. using
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <screen>apt-get install linux-headers-2.6.26-2-686</screen></para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync </listitem>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>In Linux and Solaris guests, VirtualBox graphics and mouse
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync integration goes through the X Window System. VirtualBox can use
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync the X.Org variant of the system (or XFree86 version 4.3 which is
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync identical to the first X.Org release). During the installation process,
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync the X.Org display server will be set up to use the graphics and mouse
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync drivers which come with the Guest Additions.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>After installing the Guest Additions into a fresh installation of
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync a supported Linux distribution or Solaris system (many unsupported
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync systems will work correctly too), the guest's graphics
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync mode will change to fit the size of the VirtualBox window
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync on the host when it is resized. You can also ask the guest system to
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync switch to a particular resolution by sending a "video mode hint" using
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync the <computeroutput>VBoxManage</computeroutput> tool.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Multiple guest monitors are supported in guests using the X.Org
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync server version 1.3 (which is part of release 7.3 of the X Window System
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync version 11) or a later version. The layout of the guest screens can
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync be adjusted as needed using the tools which come with the guest
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync operating system.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>If you want to understand more about the details of how the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync X.Org drivers are set up (in particular if you wish to use them in a
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync setting which our installer doesn't handle correctly), you should read
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>The Guest Additions can simply be updated by going through the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync installation procedure again with an updated CD-ROM image. This will
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync replace the drivers with updated versions. You should reboot after
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync updating the Guest Additions.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <title>Uninstalling the Linux Guest Additions</title>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>If you have a version of the Guest Additions installed on your
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync virtual machine and wish to remove it without installing new ones, you
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync can do so by inserting the Guest Additions CD image into the virtual
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync CD-ROM drive as described above and running the installer for the
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync current Guest Additions with the "uninstall" parameter from the path
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync that the CD image is mounted on in the guest: <screen>sh /VBoxLinuxAdditions.run uninstall</screen></para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>While this will normally work without issues, you may need to do some
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync manual cleanup of the guest (particularly of the XFree86Config or
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync xorg.conf file) in some cases, particularly if the Additions version
c15756b1e154b99401e0798ebdaa2f954c1378fevboxsync installed or the guest operating system were very old, or if you made
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync your own changes to the Guest Additions setup after you installed
f95bbcb7d049de34d389c3ed502a4b9fe478ea3cvboxsync them.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Starting with version 3.1.0, you can uninstall the Additions by
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync invoking <screen>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING/uninstall.sh</screen>Please
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <computeroutput>/opt/VBoxGuestAdditions-$VBOX_VERSION_STRING</computeroutput>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync with the correct Guest Additions installation directory.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync for Solaris take the form of a set of device drivers and system
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync applications which may be installed in the guest operating
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync system.</para>
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync <para>The following Solaris distributions are officially
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync supported:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <itemizedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Solaris Nevada/SXDE/SXCE (build 82 and higher);</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>OpenSolaris (Developer Preview 2 and higher; this includes
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync OpenSolaris 2008.05, 2008.11 and 2009.06);</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </itemizedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Other distributions may work if they are based on comparable
2f57ee9072f1e08bf2289054ae226559500e5781vboxsync software releases.</para>
8bfe66cdf44bdbbf326f0716e7af59809db4f53dvboxsync <title>Installing the Solaris Guest Additions</title>
2776a9429e74dc1c3a91dee752d7d7a213e5f5cfvboxsync <para>The VirtualBox Guest Additions for Solaris are provided on the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync same ISO CD-ROM as the Additions for Windows and Linux described
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync above. They also come with an installation program guiding you through
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync the setup process.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Installation involves the following steps:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <orderedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Mount the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>VBoxGuestAdditions.iso</computeroutput> file as
6160306df39548f807965d1b3e6953ca2ce92847vboxsync your Solaris guest's virtual CD-ROM drive, exactly the same way as
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync described for a Windows guest in <xref
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>If in case the CD-ROM drive on the guest doesn't get mounted
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync (observed on some versions of Solaris 10), execute as root:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Change to the directory where your CD-ROM drive is mounted
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync and execute as root:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <screen>pkgadd -G -d /VBoxSolarisAdditions.pkg</screen>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Choose "1" and confirm installation of the Guest Additions
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync package. After the installation is complete, re-login to X server
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync on your guest to activate the X11 Guest Additions.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </orderedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <title>Uninstalling the Solaris Guest Additions</title>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The Solaris Guest Additions can be safely removed by removing
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync the package from the guest. Open a root terminal session and
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync execute:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <title>Updating the Solaris Guest Additions</title>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The Guest Additions should be updated by first uninstalling the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync existing Guest Additions and then installing the new ones. Attempting
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync to install new Guest Additions without removing the existing ones is
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync not possible.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>VirtualBox also ships with a set of drivers that improve running
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync OS/2 in a virtual machine. Due to restrictions of OS/2 itself, this
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync variant of the Guest Additions has a limited feature set; see <xref
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The OS/2 Guest Additions are provided on the same ISO CD-ROM as
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync those for the other platforms. As a result, mount the ISO in OS/2 as
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync described previously. The OS/2 Guest Additions are located in the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync directory <computeroutput>\32bit\OS2</computeroutput>.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>As we do not provide an automatic installer at this time, please
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync refer to the <computeroutput>readme.txt</computeroutput> file in that
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync directory, which describes how to install the OS/2 Guest Additions
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync manually.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>With the "shared folders" feature of VirtualBox, you can access
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync files of your host system from within the guest system. This is similar
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync how you would use network shares in Windows networks -- except that shared
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync folders do not need require networking, only the Guest Additions. Shared
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Folders are supported with Windows (2000 or newer), Linux and Solaris
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync guests.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Shared folders must physically reside on the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <emphasis>host</emphasis> and are then shared with the guest, which uses a
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync special file system driver in the Guest Addition to talk to the host. For
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Windows guests, shared folders are implemented as a pseudo-network
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync redirector; for Linux and Solaris guests, the Guest Additions provide a
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync virtual file system.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>To share a host folder with a virtual machine in VirtualBox, you
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync must specify the path of that folder and choose for it a "share name" that
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync the guest can use to access it. Hence, first create the shared folder on
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync the host; then, within the guest, connect to it.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>There are several ways in which shared folders can be set up for a
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync particular virtual machine:<itemizedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>In the window of a running VM, you can select "Shared folders"
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync from the "Devices" menu, or click on the folder icon on the status
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync bar in the bottom right corner.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>If a VM is not currently running, you can configure shared
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync folders in each virtual machine's "Settings" dialog.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>From the command line, you can create shared folders using
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync VBoxManage, as follows: <screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen></para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>See <xref linkend="vboxmanage-sharedfolder" /> for
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync details.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <orderedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>VM shares which are only available to the VM for which they have
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync been defined;</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>transient VM shares, which can be added and removed at runtime
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync and do not persist after a VM has stopped; for these, add the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>--transient</computeroutput> option to the above
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync command line.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </orderedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Shared folders have read/write access to the files at the host path
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync by default. To restrict the guest to have read-only access, create a
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync read-only shared folder. This can either be achieved using the GUI or by
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync appending the parameter <computeroutput>--readonly</computeroutput> when
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync creating the shared folder with VBoxManage.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Starting with version 4.0, VirtualBox shared folders also support
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync symbolic links (<emphasis role="bold">symlinks</emphasis>), under the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync following conditions:<orderedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The host operating system must support symlinks (i.e. a Mac,
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Linux or Solaris host is required).</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
2776a9429e74dc1c3a91dee752d7d7a213e5f5cfvboxsync <para>Currently only Linux Guest Additions support symlinks.</para>
2776a9429e74dc1c3a91dee752d7d7a213e5f5cfvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>You can mount the shared folder from inside a VM the same way as
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync you would mount an ordinary network share:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>In a Windows guest, shared folders are browseable and
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync therefore visible in Windows Explorer. So, to attach the host's
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync shared folder to your Windows guest, open Windows Explorer and
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync look for it under "My Networking Places" -> "Entire Network"
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync -> "VirtualBox Shared Folders". By right-clicking on a shared
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync folder and selecting "Map network drive" from the menu that pops
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync up, you can assign a drive letter to that shared folder.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Alternatively, on the Windows command line, use the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync following:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>While <computeroutput>vboxsvr</computeroutput> is a fixed
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync name (note that <computeroutput>vboxsrv</computeroutput> would
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync also work), replace "x:" with the drive letter that you want to
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync use for the share, and <computeroutput>sharename</computeroutput>
6160306df39548f807965d1b3e6953ca2ce92847vboxsync with the share name specified with
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync <computeroutput>VBoxManage</computeroutput>.</para>
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync </listitem>
0c014c926ca775cfa9ceb2bbd322cd08efb06e3dvboxsync <para>In a Linux guest, use the following command:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>To mount a shared folder during boot, add the following
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <screen>sharename mountpoint vboxsf defaults 0 0</screen>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>In a Solaris guest, use the following command:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Replace <computeroutput>sharename</computeroutput> (use
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync lowercase) with the share name specified with
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>VBoxManage</computeroutput> or the GUI, and
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>mountpoint</computeroutput> with the path where
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync you want the share to be mounted on the guest (e.g.
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>/mnt/share</computeroutput>). The usual mount
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync rules apply, that is, create this directory first if it does not
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync exist yet.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Here is an example of mounting the shared folder for the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync user "jack" on Solaris:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <screen>$ id
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsyncuid=5000(jack) gid=1(other)
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync$ cd ~/mount
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Beyond the standard options supplied by the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>mount</computeroutput> command, the following are
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync available:</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>to set the character set used for I/O operations (utf8 by
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync default) and</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>to specify the character set used for the shared folder name
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync (utf8 by default).</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The generic mount options (documented in the mount manual
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync page) apply also. Especially useful are the options
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>mode</computeroutput>, as they allow access by
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync normal users (in read/write mode, depending on the settings) even
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync if root has mounted the filesystem.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Starting with version 4.0, VirtualBox can mount shared folders
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync automatically, at your option. If automatic mounting is enabled for a
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync specific shared folder, the Guest Additions will automatically mount
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync that folder as soon as a user logs into the guest OS. The details depend
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync on the guest OS type:<itemizedlist>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>With <emphasis role="bold">Windows guests,</emphasis> any
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync auto-mounted shared folder will receive its own drive letter (e.g.
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>E:</computeroutput>) depending on the free drive
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync letters remaining in the guest.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>If there no free drive letters left, auto-mounting will
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync fail; as a result, the number of auto-mounted shared folders is
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync typically limited to 22 or less with Windows guests.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>With <emphasis role="bold">Linux guests,</emphasis>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync auto-mounted shared folders are mounted into the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>/media</computeroutput> directory, along with the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync prefix <computeroutput>sf_</computeroutput>. For example, the
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync shared folder <computeroutput>myfiles</computeroutput> would be
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync mounted to <computeroutput>/media/sf_myfiles</computeroutput> on
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Linux and <computeroutput>/mnt/sf_myfiles</computeroutput> on
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Solaris.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>The guest property
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync determines the prefix that is used. Change that guest property to
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync a value other than "sf" to change that prefix; see <xref
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync linkend="guestadd-guestprops" /> for details.<note>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>Access to auto-mounted shared folders is only
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync granted to the user group
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>vboxsf</computeroutput>, which is created by
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync the VirtualBox Guest Additions installer. Hence guest users
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync access or to have read-only access in case the folder is not
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync mapped writable.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para>To change the mount directory to something other than
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>/media</computeroutput>, you can set the guest
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput>.</para>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync </listitem>
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync <para><emphasis role="bold">Solaris guests</emphasis> behave like
0a587d4e0fc72d110f051402aaa9767a6b2dab5dvboxsync Linux guests except that <computeroutput>/mnt</computeroutput> is
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync used as the default mount directory instead of
5020e414c2c2d6022c49ca9e53ce553f4dd6b186vboxsync </listitem>
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync <para>To have any changes to auto-mounted shared folders applied while a
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync VM is running, the guest OS needs to be rebooted. (This applies only to
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync auto-mounted shared folders, not the ones which are mounted
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync manually.)</para>
8a351244ec1c566d104757adbc19693c05e3771avboxsync <title>Hardware 3D acceleration (OpenGL and Direct3D 8/9)</title>
8a351244ec1c566d104757adbc19693c05e3771avboxsync <para>The VirtualBox Guest Additions contain experimental hardware 3D
8a351244ec1c566d104757adbc19693c05e3771avboxsync support for Windows, Linux and Solaris guests.<footnote>
74d21c63c575afd49f41ad5069337a8e966095cevboxsync <para>OpenGL support for Windows guests was added with VirtualBox
74d21c63c575afd49f41ad5069337a8e966095cevboxsync 2.1; support for Linux and Solaris followed with VirtualBox 2.2.
74d21c63c575afd49f41ad5069337a8e966095cevboxsync With VirtualBox 3.0, Direct3D 8/9 support was added for Windows
74d21c63c575afd49f41ad5069337a8e966095cevboxsync guests. OpenGL 2.0 is now supported as well.
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync With VirtualBox 4.1 Windows Aero theme support is added for
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync Windows Vista and Windows 7 guests (experimental)</para>
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync <para>With this feature, if an application inside your virtual machine
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync uses 3D features through the OpenGL or Direct3D 8/9 programming
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync interfaces, instead of emulating them in software (which would be slow),
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync VirtualBox will attempt to use your host's 3D hardware. This works for
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync all supported host platforms (Windows, Mac, Linux, Solaris), provided
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync that your host operating system can make use of your accelerated 3D
db94e7d62bf53f26966bdfddcc2006a426a20c95vboxsync hardware in the first place.</para>
db94e7d62bf53f26966bdfddcc2006a426a20c95vboxsync <para>The 3D acceleration currently has the following
db94e7d62bf53f26966bdfddcc2006a426a20c95vboxsync preconditions:<orderedlist>
8a351244ec1c566d104757adbc19693c05e3771avboxsync <para>It is only available for certain Windows, Linux and Solaris
8a351244ec1c566d104757adbc19693c05e3771avboxsync guests. In particular:<itemizedlist>
8a351244ec1c566d104757adbc19693c05e3771avboxsync <para>3D acceleration with Windows guests requires Windows
8a351244ec1c566d104757adbc19693c05e3771avboxsync 2000, Windows XP, Vista or Windows 7. Both OpenGL and
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync Direct3D 8/9 (not with Windows 2000) are supported
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync (experimental).</para>
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync </listitem>
9ce778d861807ac39e2be5be9e458e4f5dff0c76vboxsync <para>OpenGL on Linux requires kernel 2.6.27 and higher as
f91efc43d43a203309428fd6781795438d12053evboxsync well as X.org server version 1.5 and higher. Ubuntu 10.10
f91efc43d43a203309428fd6781795438d12053evboxsync and Fedora 14 have been tested and confirmed as
9ce778d861807ac39e2be5be9e458e4f5dff0c76vboxsync working.</para>
9ce778d861807ac39e2be5be9e458e4f5dff0c76vboxsync </listitem>
f91efc43d43a203309428fd6781795438d12053evboxsync <para>OpenGL on Solaris guests requires X.org server version
f91efc43d43a203309428fd6781795438d12053evboxsync 1.5 and higher.</para>
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync </listitem>
525ad8ace7233c826f5f2c77924435f8ad901250vboxsync </listitem>
525ad8ace7233c826f5f2c77924435f8ad901250vboxsync <para>For the basic Direct3D acceleration to work in a Windows Guest,
74d21c63c575afd49f41ad5069337a8e966095cevboxsync VirtualBox needs to replace Windows system files in the
f91efc43d43a203309428fd6781795438d12053evboxsync virtual machine. As a result, the Guest Additions installation
f91efc43d43a203309428fd6781795438d12053evboxsync program offers Direct3D acceleration as an option that must
74d21c63c575afd49f41ad5069337a8e966095cevboxsync be explicitly enabled. Also, you must install the Guest
74d21c63c575afd49f41ad5069337a8e966095cevboxsync Additions in "Safe Mode". This does <emphasis role="bold">not</emphasis>
675122ef85cb9b281514a490555277edf622a3b6vboxsync apply to the experimental WDDM Direct3D video
8a351244ec1c566d104757adbc19693c05e3771avboxsync driver available for Vista and Windows 7 guests,
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync </listitem>
f91efc43d43a203309428fd6781795438d12053evboxsync <para>Because 3D support is still experimental at this time, it is
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync disabled by default and must be <emphasis role="bold">manually
286e1170c6f37a765613831110da3209f8f12a19vboxsync <para>Enabling 3D acceleration may expose security holes to
286e1170c6f37a765613831110da3209f8f12a19vboxsync malicious software running in the guest. The third-party code
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync that VirtualBox uses for this purpose (Chromium) is not
be675c62a67fc41bf1fd195052b1c0821c42f7cdvboxsync hardened enough to prevent every risky 3D operation on the
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync host.</para>
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync </listitem>
ebef0a58eb2fa54c57ab4a2f349f976aa9dab6b1vboxsync <para>With VirtualBox 4.1, Windows Aero theme support is added for
ebef0a58eb2fa54c57ab4a2f349f976aa9dab6b1vboxsync Windows Vista and Windows 7 guests. To enable Aero theme support,
ebef0a58eb2fa54c57ab4a2f349f976aa9dab6b1vboxsync the experimental VirtualBox WDDM video driver must be installed,
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync which is available with the Guest Additions installation.
fab043267ebe930bb8269d270efaa2821405be81vboxsync Since the WDDM video driver is still experimental at this time, it is
8a351244ec1c566d104757adbc19693c05e3771avboxsync not installed by default and must be <emphasis role="bold">manually
fab043267ebe930bb8269d270efaa2821405be81vboxsync selected</emphasis> in the Guest Additions installer by answering "No"
fab043267ebe930bb8269d270efaa2821405be81vboxsync int the "Would you like to install basic Direct3D support" dialog
fab043267ebe930bb8269d270efaa2821405be81vboxsync displayed when the Direct3D feature is selected.
1990c7f52246ff93bfc1df98194f500ade34c163vboxsync <note><para>Unlike the current basic Direct3D support, the WDDM video
1990c7f52246ff93bfc1df98194f500ade34c163vboxsync driver installation does <emphasis role="bold">not</emphasis> require
1990c7f52246ff93bfc1df98194f500ade34c163vboxsync <para>The Aero theme is not enabled by default. To enable it<itemizedlist>
9a04f33a4f276251cd3df87a20ae4cf698b55e49vboxsync <para>In Windows Vista guest: right-click on the desktop, in the
22f67b676aef99db0a92a26e49e4e1e87e0d79c7vboxsync contect menu select "Personalize", then select "Windows Color and Appearance"
9a04f33a4f276251cd3df87a20ae4cf698b55e49vboxsync in the "Personalization" window, in the "Appearance Settings" dialog select
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync <para>In Windows 7 guest: right-click on the desktop, in the
2680cda774ce0a17cfb9f095eceab86012871852vboxsync contect menu select "Personalize" and select any Aero theme
2680cda774ce0a17cfb9f095eceab86012871852vboxsync </itemizedlist>
2680cda774ce0a17cfb9f095eceab86012871852vboxsync <para>Technically, VirtualBox implements this by installing an
2680cda774ce0a17cfb9f095eceab86012871852vboxsync additional hardware 3D driver inside your guest when the Guest Additions
2680cda774ce0a17cfb9f095eceab86012871852vboxsync are installed. This driver acts as a hardware 3D driver and reports to
2680cda774ce0a17cfb9f095eceab86012871852vboxsync the guest operating system that the (virtual) hardware is capable of 3D
2680cda774ce0a17cfb9f095eceab86012871852vboxsync hardware acceleration. When an application in the guest then requests
2680cda774ce0a17cfb9f095eceab86012871852vboxsync hardware acceleration through the OpenGL or Direct3D programming
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync interfaces, these are sent to the host through a special communication
b36b66d7994271ff9e9f9f88c34ecd2d2abbb761vboxsync tunnel implemented by VirtualBox, and then the <emphasis>host</emphasis>
9e167a039ee344e1f3d84923fb49544b4a53fc21vboxsync performs the requested 3D operation via the host's programming
9e167a039ee344e1f3d84923fb49544b4a53fc21vboxsync interfaces.</para>
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync <title>Hardware 2D video acceleration for Windows guests</title>
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync <para>Starting with version 3.1, the VirtualBox Guest Additions contain
f38f547fbcd164fcd393bfef62e6227ed74a7ed3vboxsync experimental hardware 2D video acceleration support for Windows
f38f547fbcd164fcd393bfef62e6227ed74a7ed3vboxsync guests.</para>
f38f547fbcd164fcd393bfef62e6227ed74a7ed3vboxsync <para>With this feature, if an application (e.g. a video player) inside
f38f547fbcd164fcd393bfef62e6227ed74a7ed3vboxsync your Windows VM uses 2D video overlays to play a movie clip, then
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync VirtualBox will attempt to use your host's video acceleration hardware
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync instead of performing overlay stretching and color conversion in
06616217ad41cbc8f07b6d82572cb1af7dd3ef1fvboxsync software (which would be slow). This currently works for Windows, Linux
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync and Mac host platforms, provided that your host operating system can
c677b1f8f392286ea84dae315d8ef0c872f0001fvboxsync make use of 2D video acceleration in the first place.</para>
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync <para>The 2D video acceleration currently has the following
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync preconditions:<orderedlist>
d4b1149f56963cb46ba2ae588174ed8687f14d0dvboxsync <para>It is only available for Windows guests (XP or
25f37023cbb695bd29b60919b530441f33dbb787vboxsync later).</para>
25f37023cbb695bd29b60919b530441f33dbb787vboxsync </listitem>
25f37023cbb695bd29b60919b530441f33dbb787vboxsync <para>The Guest Additions must be installed.</para>
f8bc40c66663c670e4488c3a49361f062a5261c4vboxsync </listitem>
f8bc40c66663c670e4488c3a49361f062a5261c4vboxsync <para>Because 2D support is still experimental at this time, it is
f8bc40c66663c670e4488c3a49361f062a5261c4vboxsync disabled by default and must be <emphasis role="bold">manually
afa65297d494f49dccdd289c3273984a01dd7fdfvboxsync </listitem>
2680cda774ce0a17cfb9f095eceab86012871852vboxsync <para>Technically, VirtualBox implements this by exposing video overlay
2680cda774ce0a17cfb9f095eceab86012871852vboxsync DirectDraw capabilities in the Guest Additions video driver. The driver
2680cda774ce0a17cfb9f095eceab86012871852vboxsync sends all overlay commands to the host through a special communication
2680cda774ce0a17cfb9f095eceab86012871852vboxsync tunnel implemented by VirtualBox. On the host side, OpenGL is then used
2680cda774ce0a17cfb9f095eceab86012871852vboxsync to implement color space transformation and scaling</para>
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync <para>With the "seamless windows" feature of VirtualBox, you can have the
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync windows that are displayed within a virtual machine appear side by side
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync next to the windows of your host. This feature is supported for the
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync following guest operating systems (provided that the Guest Additions are
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync installed):<itemizedlist>
809093568ec298f9753a7e2fa85025b04fe73196vboxsync <para>Windows guests (support added with VirtualBox 1.5);</para>
809093568ec298f9753a7e2fa85025b04fe73196vboxsync </listitem>
7929df8778ba70408c2c6c5975d3a48028405c56vboxsync <para>Supported Linux or Solaris guests running the X Window System
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync (added with VirtualBox 1.6).</para>
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync </listitem>
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync <para>After seamless windows are enabled (see below), VirtualBox
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync suppresses the display of the Desktop background of your guest, allowing
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync you to run the windows of your guest operating system seamlessly next to
f659e3d7e0e5f40fc03d48c1ec5f761c3e4afc2bvboxsync the windows of your host:</para>
c0963ba96a9608f286879eb8c3a76139b7a4c0acvboxsync <imageobject>
c0963ba96a9608f286879eb8c3a76139b7a4c0acvboxsync <imagedata align="center" fileref="images/seamless.png" width="14cm" />
c0963ba96a9608f286879eb8c3a76139b7a4c0acvboxsync </imageobject>
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync </mediaobject>To enable seamless mode, after starting the virtual
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync machine, press the Host key (normally the right control key) together with
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync "L". This will enlarge the size of the VM's display to the size of your
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync host screen and mask out the guest operating system's background. To go
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync back to the "normal" VM display (i.e. to disable seamless windows), press
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync the Host key and "L" again.</para>
2027727c11c26b0346a6b497fbbc89208b3e1b8avboxsync <para>Starting with version 2.1, VirtualBox allows for requesting certain
2027727c11c26b0346a6b497fbbc89208b3e1b8avboxsync properties from a running guest, provided that the VirtualBox Guest
2027727c11c26b0346a6b497fbbc89208b3e1b8avboxsync Additions are installed and the VM is running. This is good for two
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsync things:<orderedlist>
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync <para>A number of predefined VM characteristics are automatically
809093568ec298f9753a7e2fa85025b04fe73196vboxsync maintained by VirtualBox and can be retrieved on the host, e.g. to
809093568ec298f9753a7e2fa85025b04fe73196vboxsync monitor VM performance and statistics.</para>
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync </listitem>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>In addition, arbitrary string data can be exchanged between
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync guest and host. This works in both directions.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync </listitem>
592e94c48db09e5f861b8882d02caeb4db7714c4vboxsync <para>To accomplish this, VirtualBox establishes a private communication
592e94c48db09e5f861b8882d02caeb4db7714c4vboxsync channel between the VirtualBox Guest Additions and the host, and software
592e94c48db09e5f861b8882d02caeb4db7714c4vboxsync on both sides can use this channel to exchange string data for arbitrary
592e94c48db09e5f861b8882d02caeb4db7714c4vboxsync purposes. Guest properties are simply string keys to which a value is
592e94c48db09e5f861b8882d02caeb4db7714c4vboxsync attached. They can be set (written to) by either the host and the guest,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync and they can also be read from both sides.</para>
447cbf113f44132911fc13dc33cb26603759b82evboxsync <para>In addition to establishing the general mechanism of reading and
447cbf113f44132911fc13dc33cb26603759b82evboxsync writing values, a set of predefined guest properties is automatically
447cbf113f44132911fc13dc33cb26603759b82evboxsync maintained by the VirtualBox Guest Additions to allow for retrieving
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync interesting guest data such as the guest's exact operating system and
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync service pack level, the installed version of the Guest Additions, users
809093568ec298f9753a7e2fa85025b04fe73196vboxsync that are currently logged into the guest OS, network statistics and more.
809093568ec298f9753a7e2fa85025b04fe73196vboxsync These predefined properties are all prefixed with
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync <computeroutput>/VirtualBox/</computeroutput> and organized into a
ae02c60a3d8dd9eccc4f56d2d88c7343f35e7aabvboxsync hierarchical tree of keys.</para>
809093568ec298f9753a7e2fa85025b04fe73196vboxsync <para>Some of this runtime information is shown when you select "Session
809093568ec298f9753a7e2fa85025b04fe73196vboxsync Information Dialog" from a virtual machine's "Machine" menu.</para>
f28b1fb910aed70e753a47f8a0ef64817d73869dvboxsync <para>A more flexible way to use this channel is via the
f28b1fb910aed70e753a47f8a0ef64817d73869dvboxsync <computeroutput>VBoxManage guestproperty</computeroutput> command set; see
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync <xref linkend="vboxmanage-guestproperty" /> for details. For example, to
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync have <emphasis>all</emphasis> the available guest properties for a given
534226d9c71bac7817fbcfeace5cf548084d7f6cvboxsync running VM listed with their respective values, use this:<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsyncVirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsync(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsyncAll rights reserved.
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsyncName: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition,
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsync timestamp: 1229098278843087000, flags:
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsyncName: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001,
09f79746341ca60faee2b249d46f67c211c5fc0avboxsync timestamp: 1229098278950553000, flags:
09f79746341ca60faee2b249d46f67c211c5fc0avboxsyncName: /VirtualBox/GuestInfo/OS/ServicePack, value: 1,
09f79746341ca60faee2b249d46f67c211c5fc0avboxsync timestamp: 1229098279122627000, flags:
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync Guest Additions, timestamp: 1229098279269739000, flags:
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync timestamp: 1229098279345664000, flags:
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsyncName: /VirtualBox/GuestAdd/Version, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD,
a89bd5bcd9aba1ea74ec3b0e010e63fbb888441fvboxsync timestamp: 1229098279479515000, flags:
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncName: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
0b7373c1fe8e9c46674926e4f459606ec9018e0cvboxsync timestamp: 1229098279651731000, flags:
0b7373c1fe8e9c46674926e4f459606ec9018e0cvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
0b7373c1fe8e9c46674926e4f459606ec9018e0cvboxsync timestamp: 1229098279804835000, flags:
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync timestamp: 1229098279880611000, flags:
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncName: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync timestamp: 1229098279882618000, flags:
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync timestamp: 1229098279883195000, flags:
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncName: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync timestamp: 1229098279885027000, flags:
f9aab99c9045e0f7688b2e98e1deb3062bdf467bvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
f9aab99c9045e0f7688b2e98e1deb3062bdf467bvboxsync timestamp: 1229098279886838000, flags:
f9aab99c9045e0f7688b2e98e1deb3062bdf467bvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
04a4a8596f685ddb2ec94fca6ae55e21a49c26bavboxsync timestamp: 1229098279890600000, flags:
f9aab99c9045e0f7688b2e98e1deb3062bdf467bvboxsyncName: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
f9aab99c9045e0f7688b2e98e1deb3062bdf467bvboxsync timestamp: 1229098279893056000, flags:
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsyncName: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsync timestamp: 1229098279895767000, flags:
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsyncName: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsync timestamp: 1229099826317660000, flags:
8f8c5a9fef2f0a5de73d33c5bea5e0d72b5557c4vboxsyncName: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false,
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync timestamp: 1229098455580553000, flags:
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync timestamp: 1229099826299785000, flags:
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsyncName: /VirtualBox/HostInfo/GUI/LanguageID, value: C,
10b20f3c7135ae6975bbd2857a2f36fe999c4787vboxsync timestamp: 1229098151272771000, flags:
10b20f3c7135ae6975bbd2857a2f36fe999c4787vboxsyncName: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102,
10b20f3c7135ae6975bbd2857a2f36fe999c4787vboxsync timestamp: 1229099826300088000, flags:
10b20f3c7135ae6975bbd2857a2f36fe999c4787vboxsyncName: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync timestamp: 1229099826300220000, flags:
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsyncName: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync timestamp: 1229099826300350000, flags:
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsyncName: /VirtualBox/GuestInfo/Net/0/Status, value: Up,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync timestamp: 1229099826300524000, flags:
174f11bbd5c277153742aa5e6c3bd640bf379547vboxsyncName: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
174f11bbd5c277153742aa5e6c3bd640bf379547vboxsync timestamp: 1229099826317386000, flags:</screen></para>
174f11bbd5c277153742aa5e6c3bd640bf379547vboxsync <para>To query the value of a single property, use the "get" subcommand
174f11bbd5c277153742aa5e6c3bd640bf379547vboxsync like this:<screen>$ VBoxManage guestproperty get "Windows Vista III"
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncVirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsyncAll rights reserved.
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncValue: Windows Vista Business Edition
5d6b38b3539fa5d2437b6d70b353db5a381d5c4bvboxsync <para>To add or change guest properties from the guest, use the tool
5d6b38b3539fa5d2437b6d70b353db5a381d5c4bvboxsync <computeroutput>VBoxControl</computeroutput>. This tool is included in the
5d6b38b3539fa5d2437b6d70b353db5a381d5c4bvboxsync Guest Additions of VirtualBox 2.2 or later. When started from a Linux
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync guest, this tool requires root privileges for security reasons:<screen>$ sudo VBoxControl guestproperty enumerate
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncVirtualBox Guest Additions Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync(C) 2009-$VBOX_C_YEAR $VBOX_VENDOR
378fcd76fa7512f825251e6451c3e7ad18684185vboxsyncAll rights reserved.
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsyncName: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync timestamp: 1265813265835667000, flags: <NULL>
127cd925f5e27dde986b946b5fd99f170d0bb390vboxsyncName: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync timestamp: 1265813265836305000, flags: <NULL>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>For more complex needs, you can use the VirtualBox programming
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync interfaces; see <xref linkend="VirtualBoxAPI" />.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>Starting with version 3.2, the Guest Additions of VirtualBox allow
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync starting applications inside a VM from the host system.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>For this to work, the application needs to be installed inside the
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync guest; no additional software needs to be installed on the host.
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync Additionally, text mode output (to stdout and stderr) can be shown on the
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync host for further processing along with options to specify user credentials
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync and a timeout value (in milliseconds) to limit time the application is
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync able to run.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>This feature can be used to automate deployment of software within
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync the guest.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>Starting with version 4.0, the Guest Additions for Windows allow for
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync automatic updating (only already installed Guest Additions 4.0 or later).
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync Also, copying files from host to the guest as well as remotely creating
b9215fa9dd785324765fdfda07bf2856bf9abe3bvboxsync guest directories is available.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>To use these features, use the VirtualBox command line, see <xref
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>In server environments with many VMs; the Guest Additions can be
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync used to share physical host memory between several VMs, reducing the total
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync amount of memory in use by the VMs. If memory usage is the limiting factor
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync and CPU resources are still available, this can help with packing more VMs
b9215fa9dd785324765fdfda07bf2856bf9abe3bvboxsync on each host.</para>
ae02c60a3d8dd9eccc4f56d2d88c7343f35e7aabvboxsync <para>Starting with version 3.2, the Guest Additions of VirtualBox can
ae02c60a3d8dd9eccc4f56d2d88c7343f35e7aabvboxsync change the amount of host memory that a VM uses while the machine is
e61905c000d133c7e7beb9b37a076199d4b9838dvboxsync running. Because of how this is implemented, this feature is called
e61905c000d133c7e7beb9b37a076199d4b9838dvboxsync "memory ballooning".</para>
ffa4beeba44d26ca80cc7b43bd58d9e23fd12f96vboxsync <para>VirtualBox supports memory ballooning only on 64-bit hosts, and
850a16b57f568a57d0c251ccde881d72bb482941vboxsync it is not supported on Mac OS X hosts.</para>
e61905c000d133c7e7beb9b37a076199d4b9838dvboxsync <para>Normally, to change the amount of memory allocated to a virtual
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync machine, one has to shut down the virtual machine entirely and modify
e61905c000d133c7e7beb9b37a076199d4b9838dvboxsync its settings. With memory ballooning, memory that was allocated for a
e61905c000d133c7e7beb9b37a076199d4b9838dvboxsync virtual machine can be given to another virtual machine without having
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync to shut the machine down.</para>
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync <para>When memory ballooning is requested, the VirtualBox Guest
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync Additions (which run inside the guest) allocate physical memory from the
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync guest operating system on the kernel level and lock this memory down in
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync the guest. This ensures that the guest will not use that memory any
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync longer: no guest applications can allocate it, and the guest kernel will
59706011a62b0771b04cf9591e9d2f9b1625a38avboxsync not use it either. VirtualBox can then re-use this memory and give it to
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync another virtual machine.</para>
b342142e06843b1da73b1f7af9ae98b42a96bfeevboxsync <para>The memory made available through the ballooning mechanism is only
b342142e06843b1da73b1f7af9ae98b42a96bfeevboxsync available for re-use by VirtualBox. It is <emphasis>not</emphasis>
b342142e06843b1da73b1f7af9ae98b42a96bfeevboxsync returned as free memory to the host. Requesting balloon memory from a
b342142e06843b1da73b1f7af9ae98b42a96bfeevboxsync running guest will therefore not increase the amount of free,
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync unallocated memory on the host. Effectively, memory ballooning is
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync therefore a memory overcommitment mechanism for multiple virtual
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync machines while they are running. This can be useful to temporarily start
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync another machine, or in more complicated environments, for sophisticated
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync memory management of many virtual machines that may be running in
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync parallel depending on how memory is used by the guests.</para>
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync <para>At this time, memory ballooning is only supported through
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync VBoxManage. Use the following command to increase or decrease the size
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync of the memory balloon within a running virtual machine that has Guest
19acb3b726cb76dc781215b011b6fb79a6b5b7a0vboxsync Additions installed: <screen>VBoxManage controlvm "VM name" guestmemoryballoon <n></screen>where
da29038c3747122250928d3d41d13dd5b6cc29acvboxsync <computeroutput>"VM name"</computeroutput> is the name or UUID of the
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync virtual machine in question and
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync <computeroutput><n></computeroutput> is the amount of memory to
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync allocate from the guest in megabytes. See <xref
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync linkend="vboxmanage-controlvm" /> for more information.</para>
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync <para>You can also set a default balloon that will automatically be
926ee993b8734a9b84196a5865f3175d8c9f1fa8vboxsync requested from the VM every time after it has started up with the
b120453d1e242d864a9e41993b19b4b8290fdb49vboxsync following command: <screen>VBoxManage modifyvm "VM name" --guestmemoryballoon <n></screen></para>
b120453d1e242d864a9e41993b19b4b8290fdb49vboxsync <para>By default, no balloon memory is allocated. This is a VM setting,
b120453d1e242d864a9e41993b19b4b8290fdb49vboxsync like other <computeroutput>modifyvm</computeroutput> settings, and
09f79746341ca60faee2b249d46f67c211c5fc0avboxsync therefore can only be set while the machine is shut down; see <xref
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>Whereas memory ballooning simply reduces the amount of RAM that is
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync available to a VM, Page Fusion works differently: it avoids memory
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync duplication between several similar running VMs.</para>
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <para>In a server environment running several similar VMs (e.g. with
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync identical operating systems) on the same host, lots of memory pages are
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync identical. VirtualBox's Page Fusion technology, introduced with
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync VirtualBox 3.2, is a novel technique to efficiently identify these
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync identical memory pages and share them between multiple VMs.<note>
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync <para>VirtualBox supports Page Fusion only on 64-bit hosts, and it
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync is not supported on Mac OS X hosts. Page Fusion currently works only
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync with Windows guests (2000 and later).</para>
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync <para>The more similar the VMs on a given host are, the more efficiently
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync Page Fusion can reduce the amount of host memory that is in use. It
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync therefore works best if all VMs on a host run identical operating
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync systems (e.g. Windows XP Service Pack 2). Instead of having a complete
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync copy of each operating system in each VM, Page Fusion identifies the
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync identical memory pages in use by these operating systems and eliminates
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync the duplicates, sharing host memory between several machines
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync ("deduplication"). If a VM tries to modify a page that has been shared
f1bb7ee6f49b3aaf5ce3ed0be25e423e42081cd7vboxsync with other VMs, a new page is allocated again for that VM with a copy of
2909d70e58e87e2111fdc5265d1ab32a08d557a3vboxsync the shared page ("copy on write"). All this is fully transparent to the
2909d70e58e87e2111fdc5265d1ab32a08d557a3vboxsync virtual machine.</para>
2909d70e58e87e2111fdc5265d1ab32a08d557a3vboxsync <para>You may be familiar with this kind of memory overcommitment from
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync other hypervisor products, which call this feature "page sharing" or
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync "same page merging". However, Page Fusion differs significantly from
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync those other solutions, whose approaches have several
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync drawbacks:<orderedlist>
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync <para>Traditional hypervisors scan <emphasis>all</emphasis> guest
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync memory and compute checksums (hashes) for every single memory
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync page. Then, they look for pages with identical hashes and compare
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync the entire content of those pages; if two pages produce the same
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync hash, it is very likely that the pages are identical in content.
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync This, of course, can take rather long, especially if the system is
e3148b36fb133da92c44d7903524e5eed86bb46cvboxsync not idling. As a result, the additional memory only becomes
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync available after a significant amount of time (this can be hours or
e1594e1d0d9665d79c0cf3e08ecc63478c52ae0cvboxsync even days!). Even worse, this kind of page sharing algorithm
01085c46e50290eb010659a3eff41344652c6512vboxsync generally consumes significant CPU resources and increases the
01085c46e50290eb010659a3eff41344652c6512vboxsync virtualization overhead by 10-20%.</para>
01085c46e50290eb010659a3eff41344652c6512vboxsync <para>Page Fusion in VirtualBox uses logic in the VirtualBox Guest
946638efd276f5c1803bff831e830c395b87ca09vboxsync Additions to quickly identify memory cells that are most likely
946638efd276f5c1803bff831e830c395b87ca09vboxsync identical across VMs. It can therefore achieve most of the
57cde3e55eeea9b0ba23dfc8c6d5c142744c4fe1vboxsync possible savings of page sharing almost immediately and with
946638efd276f5c1803bff831e830c395b87ca09vboxsync almost no overhead.</para>
946638efd276f5c1803bff831e830c395b87ca09vboxsync </listitem>
e68b9c523da6665d5ef2c73b60ee8544ac954f5dvboxsync <para>Page Fusion is also much less likely to be confused by
e68b9c523da6665d5ef2c73b60ee8544ac954f5dvboxsync identical memory that it will eliminate just to learn seconds
e68b9c523da6665d5ef2c73b60ee8544ac954f5dvboxsync later that the memory will now change and having to perform a
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync highly expensive and often service-disrupting reallocation.</para>
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync </listitem>
0b7373c1fe8e9c46674926e4f459606ec9018e0cvboxsync <para>At this time, Page Fusion can only be controlled with VBoxManage,
0b7373c1fe8e9c46674926e4f459606ec9018e0cvboxsync and only while a VM is shut down. To enable Page Fusion for a VM, use
378fcd76fa7512f825251e6451c3e7ad18684185vboxsync the following command:<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen></para>
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsync <para>You can observe Page Fusion operation using some metrics.
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <computeroutput>RAM/VMM/Shared</computeroutput> shows the total amount
101c932a41c604a417b3d7c0bdeb1fec235888afvboxsync of fused pages, whereas the per-VM metric
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will return the
051eba4436f9c682f7873390fb327e8eceb9e0efvboxsync amount of fused memory for a given VM. Please refer to <xref
4b68fabb0db3e91d45de0e6fd2e8398169c7fe18vboxsync linkend="metrics" /> for information on how to query metrics.</para>