user_GuestAdditions.xml revision 6728a36898fd2be125a28e84d2115d19aa4923ed
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
<chapter>
<title id="guestadditions">Guest Additions</title>
<para>The previous chapter covered getting started with VirtualBox and
installing operating systems in a virtual machine. For any serious and
interactive use, the VirtualBox Guest Additions will make your life much
easier by providing closer integration between host and guest and improving
the interactive performance of guest systems. This chapter describes the
Guest Additions in detail.</para>
<sect1>
<title>Introduction</title>
<para>As said in <xref linkend="virtintro" />, the Guest Additions are
designed to be installed <emphasis>inside</emphasis> a virtual machine
after the guest operating system has been installed. They consist of
device drivers and system applications that optimize the guest operating
system for better performance and usability. Please see <xref
linkend="guestossupport" /> for details on what guest operating systems
are fully supported with Guest Additions by VirtualBox.</para>
<para>The VirtualBox Guest Additions for all supported guest operating
systems are provided as a single CD-ROM image file which is called
is located in the installation directory of VirtualBox. To install the
Guest Additions for a particular VM, you mount this ISO file in your VM as
a virtual CD-ROM and install from there.</para>
<para>The Guest Additions offer the following features:<glosslist>
<glossentry>
<glossterm>Mouse pointer integration</glossterm>
<glossdef>
<para>To overcome the limitations for mouse support that were
described in <xref linkend="keyb_mouse_normal" />, this provides
you with seamless mouse support. You will only have one mouse
pointer and pressing the Host key is no longer required to "free"
the mouse from being captured by the guest OS. To make this work,
a special mouse driver is installed in the guest that communicates
with the "real" mouse driver on your host and moves the guest
mouse pointer accordingly.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Better video support</glossterm>
<glossdef>
<para>While the virtual graphics card which VirtualBox emulates
for any guest operating system provides all the basic features,
the custom video drivers that are installed with the Guest
Additions provide you with extra high and non-standard video modes
as well as accelerated video performance.</para>
<para>In addition, with Windows and recent Linux, Solaris and
OpenSolaris guests, if the Guest Additions are installed, you can
resize the virtual machine's window, and the video resolution in
the guest will be automatically adjusted (as if you had manually
entered an arbitrary resolution in the guest's display
settings).</para>
<para>Finally, if the Guest Additions are installed, 3D graphics
for guest applications can be accelerated; see <xref
linkend="guestadd-3d" />.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Time synchronization</glossterm>
<glossdef>
<para>With the Guest Additions installed, VirtualBox can ensure
that the guest's system time is better synchronized with that of
the host.</para>
<para>For various reasons, the time in the guest might run at a
slightly different rate than the time on the host. The host could
be receiving updates via NTP and its own time might not run
linearly. A VM could also be paused, which stops the flow of time
in the guest for a shorter or longer period of time. When the wall
clock time between the guest and host only differs slightly, the
time synchronization service attempts to gradually and smoothly
adjust the guest time in small increments to either "catch up" or
"lose" time. When the difference is too great (e.g., a VM paused
for hours or restored from saved state), the guest time is changed
immediately, without a gradual adjustment.</para>
<para>The Guest Additions will re-synchronize the time regularly.
See <xref linkend="changetimesync" /> for how to configure the
parameters of the time synchronization mechanism.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Shared folders</glossterm>
<glossdef>
<para>These provide an easy way to exchange files between the host
and the guest. Much like ordinary Windows network shares, you can
tell VirtualBox to treat a certain host directory as a shared
folder, and VirtualBox will make it available to the guest
operating system as a network share. For details, please refer to
<xref linkend="sharedfolders" />.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Seamless windows</glossterm>
<glossdef>
<para>With this feature, the individual windows that are displayed
on the desktop of the virtual machine can be mapped on the host's
desktop, as if the underlying application was actually running on
the host. See <xref linkend="seamlesswindows" /> for
details.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Shared clipboard</glossterm>
<glossdef>
<para>With the Guest Additions installed, the clipboard of the
guest operating system can optionally be shared with your host
operating system; see <xref linkend="generalsettings" />.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Automated logons (credentials passing)</glossterm>
<glossdef>
<para>For details, please see <xref linkend="autologon" />.</para>
</glossdef>
</glossentry>
</glosslist></para>
<para>Each version of VirtualBox, even minor releases, ship with their own
version of the Guest Additions. While the interfaces through which the
VirtualBox core communicates with the Guest Additions are kept stable so
that Guest Additions already installed in a VM should continue to work
when VirtualBox is upgraded on the host, for best results, it is
recommended to keep the Guest Additions at the same version.</para>
<para>Starting with VirtualBox 3.1, the Windows and Linux Guest Additions
therefore check automatically whether they have to be updated. If the host
is running a newer VirtualBox version than the Guest Additions, a
notification with further instructions is displayed in the guest.</para>
<para>To disable this update check for the Guest Additions of a given
virtual machine, set the value of its
guest property to <computeroutput>0</computeroutput>; see <xref
linkend="guestadd-guestprops" /> for details.</para>
</sect1>
<sect1>
<title>Installing and Maintaining Guest Additions</title>
<para>Guest Additions are available for virtual machines running Windows,
Linux, Solaris or OS/2. The following sections describe the specifics of
each variant in detail.</para>
<sect2 id="additions-windows">
<title>Guest Additions for Windows</title>
<para>The VirtualBox Windows Guest Additions are designed to be
installed in a virtual machine running a Windows operating system. The
following versions of Windows guests are supported:</para>
<itemizedlist>
<listitem>
<para>Microsoft Windows NT 4.0 (any service pack)</para>
</listitem>
<listitem>
<para>Microsoft Windows 2000 (any service pack)</para>
</listitem>
<listitem>
<para>Microsoft Windows XP (any service pack)</para>
</listitem>
<listitem>
<para>Microsoft Windows Server 2003 (any service pack)</para>
</listitem>
<listitem>
<para>Microsoft Windows Server 2008</para>
</listitem>
<listitem>
<para>Microsoft Windows Vista (all editions)</para>
</listitem>
<listitem>
<para>Microsoft Windows 7 (all editions)</para>
</listitem>
</itemizedlist>
<sect3 id="mountingadditionsiso">
<title>Installation</title>
<para>In the "Devices" menu in the virtual machine's menu bar,
VirtualBox has a handy menu item named "Install guest additions",
which mounts the Guest Additions ISO file inside your virtual machine.
A Windows guest should then automatically start the Guest Additions
installer, which installs the Guest Additions into your Windows
guest.</para>
<note>
<para>For Direct 3D acceleration to work in a Windows Guest, you
must install the Guest Additions in "Safe Mode"; see <xref
linkend="KnownIssues" /> for details.</para>
</note>
<para>If you prefer to mount the additions manually, you can perform
the following steps:</para>
<orderedlist>
<listitem>
<para>Start the virtual machine in which you have installed
Windows.</para>
</listitem>
<listitem>
brings up the Virtual Media Manager described in <xref
linkend="vdis" />.</para>
</listitem>
<listitem>
<para>In the Virtual Media Manager, press the "Add" button and
browse your host file system for the
file:<itemizedlist>
<listitem>
<para>On a Windows host, you can find this file in the
VirtualBox installation directory (usually under
<computeroutput>C:\Program
files\Oracle\VirtualBox</computeroutput> ).</para>
</listitem>
<listitem>
<para>On Mac OS X hosts, you can find this file in the
application bundle of VirtualBox. (Right click on the
VirtualBox icon in Finder and choose <emphasis>Show Package
Contents</emphasis>. There it is located in the
folder.)</para>
</listitem>
<listitem>
<para>On a Linux host, you can find this file in the
<computeroutput>additions</computeroutput> folder under
where you installed VirtualBox (normally
</listitem>
<listitem>
<para>On Solaris hosts, you can find this file in the
<computeroutput>additions</computeroutput> folder under
where you installed VirtualBox (normally
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Back in the Virtual Media Manager, select that ISO file and
press the "Select" button. This will mount the ISO file and
present it to your Windows guest as a CD-ROM.</para>
</listitem>
</orderedlist>
<para>Unless you have the Autostart feature disabled in your Windows
guest, Windows will now autostart the VirtualBox Guest Additions
installation program from the Additions ISO. If the Autostart feature
has been turned off, choose
<para>The installer will add several device drivers to the Windows
driver database and then invoke the hardware detection wizard.</para>
<para>Depending on your configuration, it might display warnings that
the drivers are not digitally signed. You must confirm these in order
to continue the installation and properly install the
Additions.</para>
<para>After installation, reboot your guest operating system to
activate the Additions.</para>
</sect3>
<sect3>
<title>Updating the Windows Guest Additions</title>
<para>Windows Guest Additions can be updated by running the
installation program again, as previously described. This will then
replace the previous Additions drivers with updated versions.</para>
<para>Alternatively, you may also open the Windows Device Manager and
select "Update driver..." for two devices:</para>
<orderedlist>
<listitem>
<para>the VirtualBox Graphics Adapter and</para>
</listitem>
<listitem>
<para>the VirtualBox System Device.</para>
</listitem>
</orderedlist>
<para>For each, choose to provide your own driver and use "Have Disk"
to point the wizard to the CD-ROM drive with the Guest
Additions.</para>
</sect3>
<sect3>
<title>Unattended Installation</title>
<para>In order to allow for completely unattended guest installations,
you can specify a command line parameter to the install
launcher:</para>
<para>This automatically installs the right files and drivers for the
corresponding platform (32- or 64-bit).</para>
<note>
<para>Because of the drivers are not yet WHQL certified, you still
might get some driver installation popups, depending on the Windows
guest version.</para>
</note>
<para>For more options regarding unattended guest installations,
consult the command line help by using the command:</para>
</sect3>
<sect3 id="windows-guest-file-extraction">
<title>Manual file extraction</title>
<para>If you would like to install the files and drivers manually, you
can extract the files from the Windows Guest Additions setup by
typing:</para>
<para>To explicitly extract the Windows Guest Additions for another
platform than the current running one (e.g. 64-bit files on a 32-bit
system), you have to execute the appropriate platform installer
the <computeroutput>/extract</computeroutput> parameter.</para>
</sect3>
<sect3 id="vista_networking">
<title>Windows Vista networking</title>
<para>Earlier versions of VirtualBox provided a virtual AMD PCNet
Ethernet card to guests by default. Since Microsoft no longer ships a
driver for that card with Windows (starting with Windows Vista), if
you select Windows Vista or newer as the guest operating system for a
virtual machine, VirtualBox will instead present a virtual Intel
network controller to the guest (see <xref
linkend="nichardware" />).</para>
<para>However, if for any reason you have a 32-bit Windows Vista VM
that is configured to use an AMD PCNet card, you will have no
networking in the guest initially.</para>
<para>As a convenience, VirtualBox ships with a 32-bit driver for the
AMD PCNet card, which comes with the Windows Guest Additions. If you
install these in a 32-bit Vista guest, the driver will automatically
be installed as well. If, for some reason, you would like to install
the driver manually, you can extract the required files from the
Windows Guest Additions setup. Please consult <xref
linkend="windows-guest-file-extraction" /> on how to achieve this. You
will then find the AMD PCNet driver files in the
subdirectory of the default install directory.</para>
<para>Alternatively, change the Vista guest's VM settings to use an
Intel networking card instead of the default AMD PCNet card; see <xref
linkend="settings-network" /> for details.</para>
<para>Unfortunately, there is no 64-bit driver available for the AMD
PCNet card. So for 64-bit Windows VMs, you should always use the Intel
networking devices.</para>
</sect3>
</sect2>
<sect2>
<title>Guest Additions for Linux</title>
<para>Like the Windows Guest Additions, the VirtualBox Guest Additions
for Linux take the form of a set of device drivers and system
applications which may be installed in the guest operating
system.</para>
<para>The following Linux distributions are officially supported:</para>
<itemizedlist>
<listitem>
<para>Fedora as of Fedora Core 4;</para>
</listitem>
<listitem>
<para>Redhat Enterprise Linux as of version 3;</para>
</listitem>
<listitem>
<para>SUSE and openSUSE Linux as of version 9;</para>
</listitem>
<listitem>
<para>Ubuntu as of version 5.10.</para>
</listitem>
</itemizedlist>
<para>Many other distributions are known to work with the Guest
Additions.</para>
<para>The version of the Linux kernel supplied by default in SUSE and
openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 (server
edition) contains a bug which can cause it to crash during startup when
it is run in a virtual machine. The Guest Additions work in those
distributions.</para>
<para>Note that some Linux distributions already come with VirtualBox
Guest Additions or a part thereof. You may keep the distribution's
version of the Guest Additions but often, these are not up to date
and limited in functionality. Therefore, you can choose the install
the Guest Additions that come with VirtualBox, overriding the already
installed version. The VirtualBox Linux Guest Additions installer tries
to detect existing installation and replace them but depending on how
the distribution integrates the Guest Additions, they may require some
manual interaction. It is highly recommended to take a snapshot of the
virtual machine before overriding the installation.</para>
<sect3>
<title>Installing the Linux Guest Additions</title>
<para>The VirtualBox Guest Additions for Linux are provided on the
same ISO CD-ROM as the Additions for Windows described above. They
also come with an installation program guiding you through the setup
process, although, due to the significant differences between Linux
distributions, installation may be slightly more complex.</para>
<para>Installation generally involves the following steps:</para>
<orderedlist>
<listitem>
<para>Before installing the Guest Additions, you will have to
prepare your guest system for building external kernel modules.
This works similarly as described in <xref
linkend="externalkernelmodules" />, except that this step must now
be performed in your Linux <emphasis>guest</emphasis> instead of
on a Linux host system, as described there.</para>
<para>Again, as with Linux hosts, we recommend using DKMS for
Linux guests as well. If it is not installed, use this
or for Fedora systems: <screen>yum install dkms</screen></para>
<para>Make sure to nstall DKMS <emphasis>before</emphasis> installing the
Linux Guest Additions.</para>
</listitem>
<listitem>
<para>Mount the
your Linux guest's virtual CD-ROM drive, exactly the same way as
described for a Windows guest in <xref
linkend="mountingadditionsiso" />.</para>
</listitem>
<listitem>
<para>Change to the directory where your CD-ROM drive is mounted
and execute as root:</para>
<para>In a 64-bit Linux guest, use
instead.</para>
</listitem>
</orderedlist>
<para>For your convenience, the following step-by-step instructions
have been verified to work for freshly installed copies of the most
popular Linux distributions. After these preparational steps, you
can execute the VirtualBox Guest Additions installer as described
above.</para>
<sect4><title>Ubuntu 10.04 ("Lucid Lynx")</title><para>
<orderedlist>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>apt-get update</screen>
followed by
<screen>apt-get upgrade</screen></para>
</listitem>
<listitem>
<para>Install DKMS using
<screen>apt-get install dkms</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates and then proceed as described above.</para>
</listitem>
</orderedlist></para></sect4>
<sect4><title>Fedora 13 ("Goddard")</title><para>
<orderedlist>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>yum update</screen></para>
</listitem>
<listitem>
<para>Install DKMS and the GNU C compiler using
<screen>yum install dkms</screen>
followed by
<screen>yum install gcc</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates and then proceed as described above.</para>
</listitem>
</orderedlist></para></sect4>
<sect4><title>openSUSE 11.2</title><para>
<orderedlist>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>zypper update</screen></para>
</listitem>
<listitem>
<para>Install the make tool and the GNU C compiler using
<screen>zypper install make gcc</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates.</para>
</listitem>
<listitem>
<para>Find out which kernel you are running using
<screen>uname -a</screen>
An example would be <computeroutput>2.6.31.12-0.2-default</computeroutput>
which refers to the "default" kernel. Then install the correct kernel
development package. In the above example this would be
<screen>zypper install kernel-default-devel</screen></para>
</listitem>
<listitem>
<para>Make sure that your running kernel
(<computeroutput>uname -a</computeroutput>) and the kernel packages
you have installed (<computeroutput>rpm -qa kernel\*</computeroutput>)
have the exact same version number. Proceed with the installation as described
above.</para>
</listitem>
</orderedlist></para></sect4>
<sect4><title>SuSE Linux Enterprise Desktop (SLED) 11</title><para>
<orderedlist>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>zypper update</screen></para>
</listitem>
<listitem>
<para>Install the GNU C compiler using
<screen>zypper install gcc</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates.</para>
</listitem>
<listitem>
<para>Find out which kernel you are running using
<screen>uname -a</screen>
An example would be <computeroutput>2.6.27.19-5.1-default</computeroutput>
which refers to the "default" kernel. Then install the correct kernel
development package. In the above example this would be
<screen>zypper install kernel-syms kernel-source</screen></para>
</listitem>
<listitem>
<para>Make sure that your running kernel
(<computeroutput>uname -a</computeroutput>) and the kernel packages
you have installed (<computeroutput>rpm -qa kernel\*</computeroutput>)
have the exact same version number. Proceed with the installation as described
above.</para>
</listitem>
</orderedlist></para></sect4>
<sect4><title>Mandrake 2010</title><para>
<orderedlist>
<listitem>
<para>Mandrake ships with the VirtualBox Guest Additions which
will be replaced if you follow these steps.</para>
</listitem>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root and execute
<screen>urpmi --auto-update</screen></para>
</listitem>
<listitem><para>Reboot your system in order to activate the updates.</para>
</listitem>
<listitem><para>Install DKMS using
<screen>urpmi dkms</screen>
and make sure the choose the correct kernel-devel package when asked
by the installer (use <computeroutput>uname -a</computeroutput> to compare).</para>
</listitem>
</orderedlist></para></sect4>
<sect4><title>CentOS 5.5, Red Hat Enterprise Linux 5.5 and Oracle Enterprise
Linux 5.5</title><para>
<orderedlist>
<listitem>
<para>Add <computeroutput>divider=10</computeroutput> to the kernel boot options
</listitem>
<listitem>
<para>To update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>yum update</screen></para>
</listitem>
<listitem>
<para>Install the GNU C compiler and the kernel development packages using
<screen>yum install gcc</screen>
followed by
<screen>yum install kernel-devel</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates and then proceed as described above.</para>
</listitem>
<listitem>
<para>Note that OpenGL support is not available unless you update to a later Linux kernel.</para>
<para>In case Oracle Enterprise Linux does not find the required packages, you either have to
install them from a different source (e.g. DVD) or use Oracle's public Yum server located at
</listitem>
</orderedlist></para></sect4>
<sect4><title>Debian 5 ("Lenny")</title><para>
<orderedlist>
<listitem>
<para>In order to update your system to the latest version
of the packets, open a terminal and as root, execute
<screen>apt-get update</screen>
followed by
<screen>apt-get upgrade</screen></para>
</listitem>
<listitem>
<para>Install the make tool and the GNU C compiler using
<screen>apt-get install make gcc</screen></para>
</listitem>
<listitem>
<para>Reboot your guest system in order to activate the
updates.</para>
</listitem>
<listitem>
<para>Determine the exact version of your kernel using
<computeroutput>uname -a</computeroutput> and install the correct version
of the linux-headers package, e.g. using
<screen>apt-get install linux-headers-2.6.26-2-686</screen></para>
<listitem>
<para>Note that OpenGL support is not available unless you update to a later Linux kernel.</para>
</listitem>
</listitem>
</orderedlist></para></sect4>
</sect3>
<sect3><title>Manual setup of selected guest services</title>
<para>The VirtualBox Guest Additions contain several different
drivers. If for any reason you do not wish to set them all up, you can
install the Guest Additions using the following command:</para>
<para>(substituting <computeroutput>VBoxLinuxAdditions-amd64
</computeroutput> on a 64-bit guest).</para>
<para>After this, you will need to at least compile the kernel modules
as root (you will need to replace <emphasis>lib</emphasis> by
<emphasis>lib64</emphasis>
on some 64bit guests), and on older guests without the udev service
you will need to add the <emphasis>vboxadd</emphasis> service to the
default runlevel to ensure that the modules get loaded.</para>
<para>To setup the time synchronization service, run the command
and add the service vboxadd-service to the default runlevel. To set up
the X11 and OpenGL part of the Guest Additions, run the command
do not need to enable any services for this).</para>
<para>To recompile the guest kernel modules, use this command:
compilation you should reboot your guest to ensure that the new
modules are actually used.</para>
</sect3>
<sect3>
<title>Video acceleration and high resolution graphics modes</title>
<para>In Linux guests, VirtualBox video acceleration is available
through the X Window System. Typically, in today's Linux
distributions, this will be the X.Org server. During the installation
process, X will be set up to use the VirtualBox video driver shipped
with the Guest Additions.</para>
<para>For Linux and Solaris guests, the X.org server version 1.3 or
later is required for automatic resizing (the feature has been
disabled on Fedora 9 guests due to a bug in the X server they supply).
The server version can be checked with <computeroutput>Xorg
-version</computeroutput>.</para>
<para>You can also send video mode hints using the
<computeroutput>VBoxManage</computeroutput> tool.</para>
<para>If you are only using recent Linux guests systems, you can skip
the rest of this section. On older guest systems, whatever graphics
modes were set up before the installation will be used. If these modes
do not suit your requirements, you can change your setup by editing
the configuration file of the X server, usually found in
<para>VirtualBox can use any default X graphics mode which fits into
the virtual video memory allocated to the virtual machine, as
described in <xref linkend="generalsettings" />. You can also add your
own modes to the X server configuration file. You simply need to add
them to the "Modes" list in the "Display" subsection of the "Screen"
section. For example, the section shown here has a custom 2048x800
resolution mode added:</para>
<screen>Section "Screen"
Identifier "Default Screen"
Device "VirtualBox graphics card"
Monitor "Generic Monitor"
DefaultDepth 24
SubSection "Display"
Depth 24
Modes "2048x800" "800x600" "640x480"
EndSubSection
EndSection</screen>
</sect3>
<sect3>
<title>Updating the Linux Guest Additions</title>
<para>The Guest Additions can simply be updated by going through the
installation procedure again with an updated CD-ROM image. This will
replace the drivers with updated versions. You should reboot after
updating the Guest Additions.</para>
</sect3>
<sect3>
<title>Uninstalling the Linux Guest Additions</title>
<para>If you have a version of the Guest Additions installed on your
virtual machine and wish to remove it without installing new ones,
you can do so by inserting the Guest Additions CD image into the
virtual CD-ROM drive as described above and running the installer for
the current Guest Additions with the "uninstall" parameter from the
path that the CD image is mounted on in the guest:
<para>(substituting <computeroutput>VBoxLinuxAdditions-amd64</computeroutput>
on a 64-bit guest). While this will normally work
without issues, you may need to do some manual clean up of the guest
(particularly of the XFree86Config or xorg.conf file) in some cases,
particularly if the Additions version installed or the guest
operating system were very old, or if you made your own changes to
the Guest Additions setup after you installed them.</para>
</para>
<para>
Starting with version 3.1.0, you can uninstall the Additions
by invoking
with the Guest Additions installation directory.
</para>
</sect3>
</sect2>
<sect2>
<title>Guest Additions for Solaris</title>
<para>Like the Windows Guest Additions, the VirtualBox Guest Additions
for Solaris take the form of a set of device drivers and system
applications which may be installed in the guest operating
system.</para>
<para>The following Solaris distributions are officially
supported:</para>
<itemizedlist>
<listitem>
<para>OpenSolaris Nevada (Build 82 and higher; this includes
OpenSolaris 2008.05, 2008.11 and 2009.06);</para>
</listitem>
<listitem>
<para>OpenSolaris Indiana (Developer Preview 2 and higher);</para>
</listitem>
<listitem>
<para>Solaris 10 (u5 and higher).</para>
</listitem>
</itemizedlist>
<para>Other distributions may work if they are based on comparable
software releases.</para>
<sect3>
<title>Installing the Solaris Guest Additions</title>
<para>The VirtualBox Guest Additions for Solaris are provided on the
same ISO CD-ROM as the Additions for Windows and Linux described
above. They also come with an installation program guiding you through
the setup process.</para>
<para>Installation involves the following steps:</para>
<orderedlist>
<listitem>
<para>Mount the
your Solaris guest's virtual CD-ROM drive, exactly the same way as
described for a Windows guest in <xref
linkend="mountingadditionsiso" />.</para>
<para>If in case the CD-ROM drive on the guest doesn't get mounted
(observed on some versions of Solaris 10), execute as root:</para>
<screen>svcadm restart volfs</screen>
</listitem>
<listitem>
<para>Change to the directory where your CD-ROM drive is mounted
and execute as root:</para>
</listitem>
<listitem>
<para>Choose "1" and confirm installation of the Guest Additions
package. After the installation is complete, re-login to X server
on your guest to activate the X11 Guest Additions.</para>
</listitem>
</orderedlist>
</sect3>
<sect3>
<title>Uninstalling the Solaris Guest Additions</title>
<para>The Solaris Guest Additions can be safely removed by removing
the package from the guest. Open a root terminal session and
execute:</para>
<para><screen>pkgrm SUNWvboxguest</screen></para>
</sect3>
<sect3>
<title>Updating the Solaris Guest Additions</title>
<para>The Guest Additions should be updated by first uninstalling the
existing Guest Additions and then installing the new ones. Attempting
to install new Guest Additions without removing the existing ones is
not possible.</para>
</sect3>
</sect2>
<sect2>
<title>Guest Additions for OS/2</title>
<para>VirtualBox also ships with a set of drivers that improve running
OS/2 in a virtual machine. Due to restrictions of OS/2 itself, this
variant of the Guest Additions has a limited feature set; see <xref
linkend="KnownIssues" /> for details.</para>
<para>The OS/2 Guest Additions are provided on the same ISO CD-ROM as
those for the other platforms. As a result, mount the ISO in OS/2 as
described previously. The OS/2 Guest Additions are located in the
directory <computeroutput>\32bit\OS2</computeroutput>.</para>
<para>As we do not provide an automatic installer at this time, please
directory, which describes how to install the OS/2 Guest Additions
manually.</para>
</sect2>
</sect1>
<sect1 id="sharedfolders">
<title>Shared folders</title>
<para>With the "shared folders" feature of VirtualBox, you can access
files of your host system from within the guest system. This is similar
how you would use network shares in Windows networks -- except that shared
folders do not need require networking, so long as the Guest Additions are
installed. Shared Folders are supported with Windows (2000 or newer),
Linux and Solaris guests.</para>
<para>Shared folders must physically reside on the
<emphasis>host</emphasis> and are then shared with the guest; sharing is
accomplished using a special service on the host and a file system driver
for the guest, both of which are provided by VirtualBox. For Windows
guests, shared folders are implemented as a pseudo-network redirector; for
Linux and Solaris guests, the Guest Additions provide a virtual filesystem
driver which handles communication with the host.</para>
<para>To share a host folder with a virtual machine in VirtualBox, you
must specify the path of that folder and choose for it a "share name" that
the guest can use to access it. Hence, first create the shared folder on
the host; then, within the guest, connect to it.</para>
<para>There are several ways in which shared folders can be set up for a
particular virtual machine:<itemizedlist>
<listitem>
<para>In the graphical user interface of a running virtual machine,
you can select "Shared folders" from the "Devices" menu, or click on
the folder icon on the status bar in the bottom right corner of the
virtual machine window.</para>
</listitem>
<listitem>
<para>If a virtual machine is not currently running, you can
configure shared folders in each virtual machine's "Settings"
dialog.</para>
</listitem>
<listitem>
<para>From the command line, you can create shared folders using the
VBoxManage command line interface; see <xref
linkend="vboxmanage" />. The command is as follows: <screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen></para>
</listitem>
</itemizedlist></para>
<para>There are two types of shares:</para>
<orderedlist>
<listitem>
<para>VM shares which are only available to the VM for which they have
been defined;</para>
</listitem>
<listitem>
<para>transient VM shares, which can be added and removed at runtime
and do not persist after a VM has stopped; for these, add the
<computeroutput>--transient</computeroutput> option to the above
command line.</para>
</listitem>
</orderedlist>
by default. To restrict the guest to have read-only access, create a
read-only shared folder. This can either be achieved using the GUI or by
appending the parameter <computeroutput>--readonly</computeroutput> when
creating the shared folder with VBoxManage.</para>
<sect2 id="sf_mount_manual">
<title>Manual mounting</title>
<para>You can mount the shared folder from inside a VM the same way
as you would mount an ordinary network share:</para>
<para><itemizedlist>
<listitem>
<para>In a Windows guest, starting with VirtualBox 1.5.0, shared
folders are browseable and are therefore visible in Windows
Explorer. So, to attach the host's shared folder to your Windows
guest, open Windows Explorer and look for it under "My Networking
Places" -> "Entire Network" -> "VirtualBox Shared Folders". By
right-clicking on a shared folder and selecting "Map network drive"
from the menu that pops up, you can assign a drive letter to that
shared folder.</para>
<para>Alternatively, on the Windows command line, use the
following:</para>
<screen>net use x: \\vboxsvr\sharename</screen>
<para>While <computeroutput>vboxsvr</computeroutput> is a fixed name
(note that <computeroutput>vboxsrv</computeroutput> would also
work), replace "x:" with the drive letter that you want to use for
the share, and <computeroutput>sharename</computeroutput> with the
share name specified with
<computeroutput>VBoxManage</computeroutput>.</para>
</listitem>
<listitem>
<para>In a Linux guest, use the following command:</para>
<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
<para>To mount a shared folder during boot, add the following entry
<screen>sharename mountpoint vboxsf defaults 0 0</screen>
</listitem>
<listitem>
<para>In a Solaris guest, use the following command:</para>
<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
<para>Replace <computeroutput>sharename</computeroutput> (use
lowercase) with the share name specified with
<computeroutput>VBoxManage</computeroutput> or the GUI, and
<computeroutput>mountpoint</computeroutput> with the path where you
want the share to be mounted on the guest (e.g.
apply, that is, create this directory first if it does not exist
yet.</para>
<para>Here is an example of mounting the shared folder for the user
"jack" on OpenSolaris:</para>
<screen>$ id
uid=5000(jack) gid=1(other)
$ cd ~/mount
$ ls
$</screen>
<para>Beyond the standard options supplied by the
<computeroutput>mount</computeroutput> command, the following are
available:</para>
<screen>iocharset CHARSET</screen>
<para>to set the character set used for I/O operations (utf8 by
default) and</para>
<screen>convertcp CHARSET</screen>
<para>to specify the character set used for the shared folder name
(utf8 by default).</para>
<para>The generic mount options (documented in the mount manual
page) apply also. Especially useful are the options
<computeroutput>uid</computeroutput>,
<computeroutput>gid</computeroutput> and
<computeroutput>mode</computeroutput>, as they allow access by
root has mounted the filesystem.</para>
</listitem>
</itemizedlist></para>
</sect2>
<sect2 id="sf_mount_auto">
<title>Automatic mounting</title>
<para>Starting with version 3.3.0, VirtualBox supports automatic mounting
support for shared folders. The installed Guest Additions will then take
care of all shared folders which are marked as being auto-mounted as soon
as a user is logged in to the guest OS. This makes it more convenient
instead of mounting shared folders manually described in <xref
linkend="sf_mount_manual" />.</para>
<note>
<para>Auto-mounting currently is only supported on Windows, Linux and
Solaris guests.</para>
</note>
<para>On Windows guests an auto-mounted shared folder will be represented by an own
remaining free drive letters of the system.</para>
<para>On Linux and Solaris guests auto-mounted shared folders get mounted into
the <computeroutput>/media</computeroutput> directory, along with the prefix
<computeroutput>sf_</computeroutput>, so the shared folder <computeroutput>myfiles</computeroutput>
<para>To change the prefix <computeroutput>sf_</computeroutput> of a given
virtual machine, set the value of its <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
guest property to another value; see <xref linkend="guestadd-guestprops" /> for details.</para>
<para>To get a user full access to the auto-mounted shared folders on the guest
this user needs to be part of the newly create group "vboxsf", which is created by the
VirtualBox Guest Additions installer. Without being in that group read-only access
is provided.</para>
<para>To get changes applied, for example by adding new or deleting auto-mounted
shared folders while a VM is running, the guest OS needs to be rebooted. However,
this does not affect <xref linkend="sf_mount_manual" />.</para>
</sect2>
</sect1>
<sect1 id="seamlesswindows">
<title>Seamless windows</title>
<para>With the "seamless windows" feature of VirtualBox, you can have the
windows that are displayed within a virtual machine appear side by side
next to the windows of your host. This feature is supported for the
following guest operating systems (provided that the Guest Additions are
installed):<itemizedlist>
<listitem>
<para>Windows guests (support added with VirtualBox 1.5);</para>
</listitem>
<listitem>
version 1.3 or higher<footnote>
<para>The X server version is not the same as the version of the
entire X.org suite. You can type <computeroutput>X
-version</computeroutput> in a terminal to find out about the
X.org server version level that is currently installed.</para>
</footnote> (support added with VirtualBox 1.6). The exception is
Fedora 9, due to a bug in its X server.</para>
</listitem>
</itemizedlist></para>
<para>After seamless windows are enabled (see below), VirtualBox
suppresses the display of the Desktop background of your guest, allowing
you to run the windows of your guest operating system seamlessly next to
the windows of your host:</para>
<para><mediaobject>
<imageobject>
</imageobject>
</mediaobject>To enable seamless mode, after starting the virtual
machine, press the Host key (normally the right control key) together with
"L". This will enlarge the size of the VM's display to the size of your
host screen and mask out the guest operating system's background. To go
back to the "normal" VM display (i.e. to disable seamless windows), press
the Host key and "L" again.</para>
</sect1>
<sect1>
<title>Hardware-accelerated graphics</title>
<sect2 id="guestadd-3d">
<title>Hardware 3D acceleration (OpenGL and Direct3D 8/9)</title>
<para>The VirtualBox Guest Additions contain experimental hardware 3D
support for Windows, Linux and Solaris guests.<footnote>
<para>OpenGL support for Windows guests was added with VirtualBox
2.1; support for Linux and Solaris followed with VirtualBox 2.2.
With VirtualBox 3.0, Direct3D 8/9 support was added for Windows
guests. OpenGL 2.0 is now supported as well.</para>
</footnote></para>
<para>With this feature, if an application inside your virtual machine
uses 3D features through the OpenGL or Direct3D 8/9 programming
interfaces, instead of emulating them in software (which would be slow),
VirtualBox will attempt to use your host's 3D hardware. This works for
all supported host platforms (Windows, Mac, Linux, Solaris), provided
that your host operating system can make use of your accelerated 3D
hardware in the first place.</para>
<para>The 3D acceleration currently has the following
preconditions:<orderedlist>
<listitem>
<para>It is only available for certain Windows, Linux and Solaris
guests. In particular:<itemizedlist>
<listitem>
<para>For Windows guests, support is restricted to 32-bit
versions of XP and Vista. Both OpenGL and Direct3D 8/9 are
supported (experimental).</para>
</listitem>
<listitem>
<para>OpenGL on Linux requires kernel 2.6.27 and higher as
well as X.org server version 1.5 and higher. Ubuntu 8.10 and
Fedora 10 have been tested and confirmed as working.</para>
</listitem>
<listitem>
<para>OpenGL on Solaris guests requires X.org server version
1.5 and higher.</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>The Guest Additions must be installed.<note>
<para>For Direct 3D acceleration to work in a Windows Guest,
VirtualBox needs to replace Windows system files in the
virtual machine. As a result, the Guest Additions installation
program offers Direct 3D acceleration as an option that must
be explicitly enabled.</para>
<para>Also, you must install the Guest Additions in "Safe
Mode"; see <xref linkend="KnownIssues" /> for details.</para>
</note></para>
</listitem>
<listitem>
<para>Because 3D support is still experimental at this time, it is
disabled by default and must be <emphasis role="bold">manually
enabled</emphasis> in the VM settings (see <xref
linkend="generalsettings" />).<note>
<para>Enabling 3D acceleration may expose security holes to
malicious software running the guest. The third-party code
that VirtualBox uses for this purpose (Chromium) is not
hardened enough to prevent every risky 3D operation on the
host.</para>
</note></para>
</listitem>
</orderedlist></para>
<para>Technically, VirtualBox implements this by installing an
additional hardware 3D driver inside your guest when the Guest Additions
are installed. This driver acts as a hardware 3D driver and reports to
the guest operating system that the (virtual) hardware is capable of 3D
hardware acceleration. When an application in the guest then requests
hardware acceleration through the OpenGL or Direct3D programming
interfaces, these are sent to the host through a special communication
tunnel implemented by VirtualBox, and then the host performs the
requested 3D operation via the host's programming interfaces.</para>
</sect2>
<sect2 id="guestadd-2d">
<title>Hardware 2D video acceleration for Windows guests</title>
<para>Starting with version 3.1, the VirtualBox Guest Additions contain
experimental hardware 2D video acceleration support for Windows
guests.</para>
<para>With this feature, if an application (e.g. a video player) inside
your Windows VM uses 2D video overlays to play a movie clip, then
VirtualBox will attempt to use your host's video acceleration hardware
instead of performing overlay stretching and color conversion in
software (which would be slow). This currently works for Windows, Linux
and Mac host platforms, provided that your host operating system can
make use of 2D video acceleration in the first place.</para>
<para>The 2D video acceleration currently has the following
preconditions:<orderedlist>
<listitem>
<para>It is only available for Windows guests (XP or
later).</para>
</listitem>
<listitem>
<para>The Guest Additions must be installed.</para>
</listitem>
<listitem>
<para>Because 2D support is still experimental at this time, it is
disabled by default and must be <emphasis role="bold">manually
enabled</emphasis> in the VM settings (see <xref
linkend="generalsettings" />).</para>
</listitem>
</orderedlist></para>
<para>Technically, VirtualBox implements this by exposing video overlay
DirectDraw capabilities in the Guest Additions video driver. The driver
sends all overlay commands to the host through a special communication
tunnel implemented by VirtualBox. On the host side, OpenGL is then used
to implement color space transformation and scaling</para>
</sect2>
</sect1>
<sect1 id="guestadd-guestprops">
<title>Guest properties</title>
<para>Starting with version 2.1, VirtualBox allows for requesting certain
properties from a running guest, provided that the VirtualBox Guest
Additions are installed and the VM is running. This is good for two
things:<orderedlist>
<listitem>
<para>A number of predefined VM characteristics are automatically
maintained by VirtualBox and can be retrieved on the host, e.g. to
monitor VM performance and statistics.</para>
</listitem>
<listitem>
<para>In addition, arbitrary string data can be exchanged between
guest and host. This works in both directions.</para>
</listitem>
</orderedlist></para>
<para>To accomplish this, VirtualBox establishes a private communication
channel between the VirtualBox Guest Additions and the host, and software
on both sides can use this channel to exchange string data for arbitrary
purposes. Guest properties are simply string keys to which a value is
attached. They can be set (written to) by either the host and the guest,
and they can also be read from both sides.</para>
<para>In addition to establishing the general mechanism of reading and
writing values, a set of predefined guest properties is automatically
maintained by the VirtualBox Guest Additions to allow for retrieving
interesting guest data such as the guest's exact operating system and
service pack level, the installed version of the Guest Additions, users
that are currently logged into the guest OS, network statistics and more.
These predefined properties are all prefixed with
<computeroutput>/VirtualBox/</computeroutput> and organized into a
hierarchical tree of keys.</para>
<para>Some of this runtime information is shown when you select "Session
Information Dialog" from a virtual machine's "Machine" menu.</para>
<para>A more flexible way to use this channel is via the
<computeroutput>VBoxManage guestproperty</computeroutput> command set; see
<xref linkend="vboxmanage-guestproperty" /> for details. For example, to
have <emphasis>all</emphasis> the available guest properties for a given
running VM listed with their respective values, use this:<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
All rights reserved.
timestamp: 1229098278843087000, flags:
timestamp: 1229098278950553000, flags:
timestamp: 1229098279122627000, flags:
Guest Additions, timestamp: 1229098279269739000, flags:
timestamp: 1229098279345664000, flags:
Name: /VirtualBox/GuestAdd/Version, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD,
timestamp: 1229098279479515000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279651731000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279804835000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279880611000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279882618000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279883195000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279885027000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279886838000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279890600000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279893056000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILDr40720,
timestamp: 1229098279895767000, flags:
timestamp: 1229099826317660000, flags:
timestamp: 1229098455580553000, flags:
timestamp: 1229099826299785000, flags:
timestamp: 1229098151272771000, flags:
timestamp: 1229099826300088000, flags:
timestamp: 1229099826300220000, flags:
timestamp: 1229099826300350000, flags:
timestamp: 1229099826300524000, flags:
timestamp: 1229099826317386000, flags:</screen></para>
<para>To query the value of a single property, use the "get" subcommand
like this:<screen>$ VBoxManage guestproperty get "Windows Vista III"
VirtualBox Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
(C) 2005-$VBOX_C_YEAR $VBOX_VENDOR
All rights reserved.
Value: Windows Vista Business Edition
</screen></para>
<para>To add or change guest properties from the guest, use the tool
<computeroutput>VBoxControl</computeroutput>. This tool is included in the
Guest Additions of VirtualBox 2.2 or later. When started from a Linux
guest, this tool requires root privileges for security reasons:<screen>$ sudo VBoxControl guestproperty enumerate
VirtualBox Guest Additions Command Line Management Interface Version $VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD
(C) 2009-$VBOX_C_YEAR $VBOX_VENDOR
All rights reserved.
timestamp: 1265813265835667000, flags: <NULL>
timestamp: 1265813265836305000, flags: <NULL>
...</screen></para>
<para>For more complex needs, you can use the VirtualBox programming
interfaces; see <xref linkend="VirtualBoxAPI" />.</para>
</sect1>
<sect1 id="guestadd-guestcontrol">
<title>Guest control</title>
<para>Starting with version 3.2, the Guest Additions of VirtualBox allow
starting applications inside a VM from the host system.</para>
<para>For this to work, the application needs to be installed inside the
guest; no additional software needs to be installed on the host.
Additionally, text mode output (to stdout and stderr) can be shown on the
host for further processing along with options to specify user
credentials and a timeout value (in milliseconds) to limit time the
application is able to run.</para>
<para>This feature can be used to automate deployment of software within
the guest.</para>
<para>To use this feature, use the VirtualBox command line. See <xref
linkend="vboxmanage-guestcontrol" /> for details.</para>
</sect1>
<sect1 id="guestadd-balloon">
<title>Memory ballooning</title>
<para>Starting with version 3.2, the Guest Additions of VirtualBox can
change the amount of memory of a virtual machine while the machine is
running. Because of how this is implemented, this feature is called
"memory ballooning".</para>
<para>Normally, to change the amount of memory allocated to a virtual
machine, one has to shut down the virtual machine entirely and change the
virtual machine's settings. With memory ballooning, memory that was
allocated for a virtual machine can be given to another virtual machine
without having to shut the machine down. This can be useful to temporarily
start another virtual machine, or in more complicated environments for
sophisticated memory management of many virtual machines that may be
running in parallel depending on how memory is used by the guests.</para>
<para>When memory ballooning is requested, the VirtualBox Guest Additions
(which run inside the guest) allocate physical memory from the guest
operating system on the kernel level and lock this memory down in the
guest. This ensures that the guest will not use that memory any longer: no
guest applications can allocate it, and the guest operating system will
not use it either. VirtualBox can then re-use this memory and give it to a
second virtual machine.</para>
<para>The memory made available through the ballooning mechanism is only
available for re-use by VirtualBox. It is <emphasis>not</emphasis>
returned as free memory to the host. Requesting balloon memory from a
running guest will therefore not increase the amount of free, unallocated
memory on the host.</para>
<para>Effectively, memory ballooning is therefore a memory overcommitment
mechanism for multiple virtual machines while they are running.</para>
<para>At this time, memory ballooning is only supported in VBoxManage, the
VirtualBox command-line utility. Use the following command to increase or
decrease the size of the memory balloon within a running virtual machine
that has Guest Additions installed: <screen>VBoxManage controlvm "VM name" guestmemoryballoon <n></screen>
where <computeroutput>"VM name"</computeroutput> is the name or UUID of
the virtual machine in question and
<computeroutput><n></computeroutput> is the amount of memory to
allocate from the guest in megabytes; see <xref
linkend="vboxmanage-controlvm" /> for more information.</para>
<para>You can also set a default balloon that will automatically be
requested from the VM every time after it has started up with the
following command: <screen>VBoxManage modifyvm "VM name" --guestmemoryballoon <n></screen></para>
<para>By default, no balloon memory is allocated. This is a VM setting,
like other <computeroutput>modifyvm</computeroutput> settings, and
therefore can only be set while the machine is shut down; see <xref
linkend="vboxmanage-modifyvm" />.</para>
<para><note>
<para>VirtualBox supports memory ballooning only on 64-bit hosts,
memory ballooning is <emphasis>not</emphasis> supported on Mac OS X
hosts.</para>
</note></para>
</sect1>
<sect1 id="guestadd-pagefusion">
<title>Page Fusion</title>
<para>Page Fusion is a novel technique to further improve VM density on the host,
i.e. a way of overcommitting resources. It was first introduced with VirtualBox 3.2
and is currently limited to VMs running Windows 2000 and later. In a typical scenario,
dozens, up to hundreds of very similar VMs are consolidated on a powerful host
computer and the level of consolidation is most often limited by the amount of RAM
that can be installed in a system at reasonable cost. Often, due to RAM exhaustion,
additional VMs cannot be started even though the host's CPUs still provide capacity.
To circumvent this restriction, hypervisors can benefit from the fact that often, VMs
are very similar (e.g. multiple VMs running Windows XP Service Pack 2) and therefore
contain a number of identical RAM cells. The hypervisor can look for such duplicate
data in memory, eliminate the redundancy (deduplication) and thereby free additional
memory.</para>
<para>Traditional hypervisors use a technique often called "page sharing" or
"same page merging" where they go through all memory and compute checksums (hashes)
for each memory page. Then, they look for pages with identical hashes and compare
the content of the pages (if two pages produce the same hash, it is very likely that
the pages are identical in content). Identical pages get eliminated so that all VMs
point to the same page as long as none of the VMs tries to modify the page. If such
a page gets modified, the previously eliminated duplicates get allocated again. All
this is fully transparent to the virtual machine. However, the classical algorithm
has several drawbacks. First of all, it takes rather long to scan the complete
memory (esp. when the system is not idling) so the additional memory only becomes
available after some time (this can be hours or even days!). Also, the whole page
sharing algorithm generally consumes significant CPU resources and increases the
virtualization overhead by 10-20%.</para>
<para>Page Fusion in VirtualBox uses the VirtualBox Guest Additions to identify
memory cells that are most likely identical across VMs and therefore achieves
most of the possible savings of page sharing almost immediately and with almost no
overhead. Page Fusion is also much less likely to be tricked by identical memory
that it will eliminate just to learn seconds later that the memory will now change
and having to perform a highly expensive and often service disrupting reallocation.
</para>
<para>Page Fusion can be enabled for a VM using:
<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen>
</para>
<para>You can observe Page Fusion operation using some metrics.
will return the amount of fused memory for a given VM. Please refer to
<xref linkend="metrics" /> for information on how to query metrics.</para>
<para><note>
<para>VirtualBox supports Page Fusion only on 64-bit host operating systems.
Mac OS X hosts are currently not supported. Page Fusion is only available for
Windows 2000 and later guests with current Guest Additions.</para>
</note></para>
</sect1>
</chapter>