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