diff options
Diffstat (limited to 'doc/manual/en_US/user_GuestAdditions.xml')
| -rw-r--r-- | doc/manual/en_US/user_GuestAdditions.xml | 2434 |
1 files changed, 2434 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_GuestAdditions.xml b/doc/manual/en_US/user_GuestAdditions.xml new file mode 100644 index 00000000..71a7946e --- /dev/null +++ b/doc/manual/en_US/user_GuestAdditions.xml @@ -0,0 +1,2434 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="guestadditions"> + + <title>Guest Additions</title> + + <para> + The previous chapter covered getting started with &product-name; and + installing operating systems in a virtual machine. For any serious + and interactive use, the &product-name; Guest Additions will make + your life much easier by providing closer integration between host + and guest and improving the interactive performance of guest + systems. This chapter describes the Guest Additions in detail. + </para> + + <sect1 id="guestadd-intro"> + + <title>Introduction to Guest Additions</title> + + <para> + As mentioned in <xref linkend="virtintro" />, the Guest Additions + are designed to be installed <emphasis>inside</emphasis> a virtual + machine after the guest operating system has been installed. They + consist of device drivers and system applications that optimize + the guest operating system for better performance and usability. + See <xref linkend="guestossupport" /> for details on what guest + operating systems are fully supported with Guest Additions by + &product-name;. + </para> + + <para> + The &product-name; Guest Additions for all supported guest + operating systems are provided as a single CD-ROM image file which + is called <computeroutput>VBoxGuestAdditions.iso</computeroutput>. + This image file is located in the installation directory of + &product-name;. To install the Guest Additions for a particular + VM, you mount this ISO file in your VM as a virtual CD-ROM and + install from there. + </para> + + <para> + The Guest Additions offer the following features: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Mouse pointer integration</emphasis>. To + overcome the limitations for mouse support described in + <xref linkend="keyb_mouse_normal" />, this feature provides + you with seamless mouse support. You will only have one mouse + pointer and pressing the Host key is no longer required to + "free" the mouse from being captured by the guest OS. To make + this work, a special mouse driver is installed in the guest + that communicates with the "real" mouse driver on your host + and moves the guest mouse pointer accordingly. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared folders.</emphasis> These provide + an easy way to exchange files between the host and the guest. + Much like ordinary Windows network shares, you can tell + &product-name; to treat a certain host directory as a shared + folder, and &product-name; will make it available to the guest + operating system as a network share, irrespective of whether + guest actually has a network. See + <xref + linkend="sharedfolders" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Better video support.</emphasis> While + the virtual graphics card which &product-name; emulates for + any guest operating system provides all the basic features, + the custom video drivers that are installed with the Guest + Additions provide you with extra high and non-standard video + modes, as well as accelerated video performance. + </para> + + <para> + In addition, with Windows, Linux, and Oracle Solaris guests, + you can resize the virtual machine's window if the Guest + Additions are installed. The video resolution in the guest + will be automatically adjusted, as if you had manually entered + an arbitrary resolution in the guest's + <emphasis role="bold">Display</emphasis> settings. See + <xref linkend="intro-resize-window" />. + </para> + + <para> + If the Guest Additions are installed, 3D graphics and 2D video + for guest applications can be accelerated. See + <xref linkend="guestadd-video" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Seamless windows.</emphasis> With this + feature, the individual windows that are displayed on the + desktop of the virtual machine can be mapped on the host's + desktop, as if the underlying application was actually running + on the host. See <xref linkend="seamlesswindows" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Generic host/guest communication + channels.</emphasis> The Guest Additions enable you to control + and monitor guest execution. The "guest properties" provide a + generic string-based mechanism to exchange data bits between a + guest and a host, some of which have special meanings for + controlling and monitoring the guest. See + <xref linkend="guestadd-guestprops" />. + </para> + + <para> + Additionally, applications can be started in a guest from the + host. See <xref linkend="guestadd-guestcontrol" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Time synchronization.</emphasis> With + the Guest Additions installed, &product-name; can ensure that + the guest's system time is better synchronized with that of + the host. + </para> + + <para> + For various reasons, the time in the guest might run at a + slightly different rate than the time on the host. The host + could be receiving updates through NTP and its own time might + not run linearly. A VM could also be paused, which stops the + flow of time in the guest for a shorter or longer period of + time. When the wall clock time between the guest and host only + differs slightly, the time synchronization service attempts to + gradually and smoothly adjust the guest time in small + increments to either "catch up" or "lose" time. When the + difference is too great, for example if a VM paused for hours + or restored from saved state, the guest time is changed + immediately, without a gradual adjustment. + </para> + + <para> + The Guest Additions will resynchronize the time regularly. See + <xref linkend="changetimesync" /> for how to configure the + parameters of the time synchronization mechanism. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shared clipboard.</emphasis> With the + Guest Additions installed, the clipboard of the guest + operating system can optionally be shared with your host + operating system. See <xref linkend="generalsettings" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Automated logins.</emphasis> Also called + credentials passing. See <xref linkend="autologon" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each version of &product-name;, even minor releases, ship with + their own version of the Guest Additions. While the interfaces + through which the &product-name; core communicates with the Guest + Additions are kept stable so that Guest Additions already + installed in a VM should continue to work when &product-name; is + upgraded on the host, for best results, it is recommended to keep + the Guest Additions at the same version. + </para> + + <para> + The Windows and Linux Guest Additions therefore check + automatically whether they have to be updated. If the host is + running a newer &product-name; version than the Guest Additions, a + notification with further instructions is displayed in the guest. + </para> + + <para> + To disable this update check for the Guest Additions of a given + virtual machine, set the value of its + <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput> + guest property to <computeroutput>0</computeroutput>. See + <xref + linkend="guestadd-guestprops" />. + </para> + + </sect1> + + <sect1 id="guestadd-install"> + + <title>Installing and Maintaining Guest Additions</title> + + <para> + Guest Additions are available for virtual machines running + Windows, Linux, Oracle Solaris, or OS/2. The following sections + describe the specifics of each variant in detail. + </para> + + <sect2 id="additions-windows"> + + <title>Guest Additions for Windows</title> + + <para> + The &product-name; Windows Guest Additions are designed to be + installed in a virtual machine running a Windows operating + system. The following versions of Windows guests are supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Microsoft Windows NT 4.0 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 2000 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows XP (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2003 (any service pack) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2008 + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Vista (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 7 (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 8 (all editions) + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows 10 RTM build 10240 + </para> + </listitem> + + <listitem> + <para> + Microsoft Windows Server 2012 + </para> + </listitem> + + </itemizedlist> + + <sect3 id="mountingadditionsiso"> + + <title>Installing the Windows Guest Additions</title> + + <para> + In the <emphasis role="bold">Devices</emphasis> menu in the + virtual machine's menu bar, &product-name; has a menu item + <emphasis role="bold">Insert Guest Additions CD + Image</emphasis>, which mounts the Guest Additions ISO file + inside your virtual machine. A Windows guest should then + automatically start the Guest Additions installer, which + installs the Guest Additions on your Windows guest. + </para> + + <para> + For other guest operating systems, or if automatic start of + software on a CD is disabled, you need to do a manual start of + the installer. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + guest, you have to install the WDDM video driver available + for Windows Vista or later. + </para> + + <para> + For Windows 8 and later, only the WDDM Direct3D video driver + is available. For basic Direct3D acceleration to work in + Windows XP guests, you have to install the Guest Additions + in Safe Mode. See <xref linkend="KnownIssues" /> for + details. + </para> + </note> + + <para> + If you prefer to mount the Guest Additions manually, you can + perform the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Start the virtual machine in which you have installed + Windows. + </para> + </listitem> + + <listitem> + <para> + Select <emphasis role="bold">Mount CD/DVD-ROM</emphasis> + from the <emphasis role="bold">Devices</emphasis> menu in + the virtual machine's menu bar and then + <emphasis role="bold">CD/DVD-ROM Image</emphasis>. This + displays the Virtual Media Manager, described in + <xref + linkend="vdis" />. + </para> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, click + <emphasis role="bold">Add</emphasis> and browse your host + file system for the + <computeroutput>VBoxGuestAdditions.iso</computeroutput> + file. + </para> + + <itemizedlist> + + <listitem> + <para> + On a Windows host, this file is in the &product-name; + installation directory, usually in + <computeroutput>C:\Program + files\Oracle\VirtualBox</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + On Mac OS X hosts, this file is in the application + bundle of &product-name;. Right-click on the + &product-name; icon in Finder and choose + <emphasis role="bold">Show Package + Contents</emphasis>. The file is located in the + <computeroutput>Contents/MacOS</computeroutput> + folder. + </para> + </listitem> + + <listitem> + <para> + On a Linux host, this file is in the + <computeroutput>additions</computeroutput> folder + where you installed &product-name;, usually + <computeroutput>/opt/VirtualBox/</computeroutput>. + </para> + </listitem> + + <listitem> + <para> + On Oracle Solaris hosts, this file is in the + <computeroutput>additions</computeroutput> folder + where you installed &product-name;, usually + <computeroutput>/opt/VirtualBox</computeroutput>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + In the Virtual Media Manager, select the ISO file and + click <emphasis role="bold">Select</emphasis> button. This + mounts the ISO file and presents it to your Windows guest + as a CD-ROM. + </para> + </listitem> + + </orderedlist> + + <para> + Unless you have the Autostart feature disabled in your Windows + guest, Windows will now autostart the &product-name; Guest + Additions installation program from the Additions ISO. If the + Autostart feature has been turned off, choose + <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from + the CD/DVD drive inside the guest to start the installer. + </para> + + <para> + The installer will add several device drivers to the Windows + driver database and then invoke the hardware detection wizard. + </para> + + <para> + Depending on your configuration, it might display warnings + that the drivers are not digitally signed. You must confirm + these in order to continue the installation and properly + install the Additions. + </para> + + <para> + After installation, reboot your guest operating system to + activate the Additions. + </para> + + </sect3> + + <sect3 id="additions-windows-updating"> + + <title>Updating the Windows Guest Additions</title> + + <para> + Windows Guest Additions can be updated by running the + installation program again. This replaces the previous + Additions drivers with updated versions. + </para> + + <para> + Alternatively, you can also open the Windows Device Manager + and select <emphasis role="bold">Update Driver...</emphasis> + for the following devices: + </para> + + <orderedlist> + + <listitem> + <para> + &product-name; Graphics Adapter + </para> + </listitem> + + <listitem> + <para> + &product-name; System Device + </para> + </listitem> + + </orderedlist> + + <para> + For each, choose the option to provide your own driver, click + <emphasis role="bold">Have Disk</emphasis> and navigate to the + CD-ROM drive with the Guest Additions. + </para> + + </sect3> + + <sect3 id="additions-windows-install-unattended"> + + <title>Unattended Installation</title> + + <para> + To avoid popups when performing an unattended installation of + the &product-name; Guest Additions, the code signing + certificates used to sign the drivers needs to be installed in + the correct certificate stores on the guest operating system. + Failure to do this will cause a typical Windows installation + to display multiple dialogs asking whether you want to install + a particular driver. + </para> + + <note> + <para> + On some Windows versions, such as Windows 2000 and Windows + XP, the user intervention popups mentioned above are always + displayed, even after importing the Oracle certificates. + </para> + </note> + + <para> + Installing the code signing certificates on a Windows guest + can be done automatically. Use the + <computeroutput>VBoxCertUtil.exe</computeroutput> utility from + the <computeroutput>cert</computeroutput> folder on the Guest + Additions installation CD. + </para> + + <para> + Use the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Log in as Administrator on the guest. + </para> + </listitem> + + <listitem> + <para> + Mount the &product-name; Guest Additions .ISO. + </para> + </listitem> + + <listitem> + <para> + Open a command line window on the guest and change to the + <computeroutput>cert</computeroutput> folder on the + &product-name; Guest Additions CD. + </para> + </listitem> + + <listitem> + <para> + Run the following command: + </para> + +<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen> + + <para> + This command installs the certificates to the certificate + store. When installing the same certificate more than + once, an appropriate error will be displayed. + </para> + </listitem> + + </orderedlist> + + <para> + To allow for completely unattended guest installations, you + can specify a command line parameter to the install launcher: + </para> + +<screen>VBoxWindowsAdditions.exe /S</screen> + + <para> + This automatically installs the right files and drivers for + the corresponding platform, either 32-bit or 64-bit. + </para> + + <note> + <para> + By default on an unattended installation on a Vista or + Windows 7 guest, there will be the XPDM graphics driver + installed. This graphics driver does not support Windows + Aero / Direct3D on the guest. Instead, the WDDM graphics + driver needs to be installed. To select this driver by + default, add the command line parameter + <computeroutput>/with_wddm</computeroutput> when invoking + the Windows Guest Additions installer. This is only required + for Vista and Windows 7. + </para> + </note> + + <note> + <para> + For Windows Aero to run correctly on a guest, the guest's + VRAM size needs to be configured to at least 128 MB. + </para> + </note> + + <para> + For more options regarding unattended guest installations, + consult the command line help by using the command: + </para> + +<screen>VBoxWindowsAdditions.exe /?</screen> + + </sect3> + + <sect3 id="windows-guest-file-extraction"> + + <title>Manual File Extraction</title> + + <para> + If you would like to install the files and drivers manually, + you can extract the files from the Windows Guest Additions + setup as follows: + </para> + +<screen>VBoxWindowsAdditions.exe /extract</screen> + + <para> + To explicitly extract the Windows Guest Additions for another + platform than the current running one, such as 64-bit files on + a 32-bit system, you must use the appropriate platform + installer. Use + <computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput> + or + <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput> + with the <computeroutput>/extract</computeroutput> parameter. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-linux"> + + <title>Guest Additions for Linux</title> + + <para> + Like the Windows Guest Additions, the &product-name; Guest + Additions for Linux are a set of device drivers and system + applications which may be installed in the guest operating + system. + </para> + + <para> + The following Linux distributions are officially supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Linux as of version 5, including UEK kernels + </para> + </listitem> + + <listitem> + <para> + Fedora as of Fedora Core 4 + </para> + </listitem> + + <listitem> + <para> + Redhat Enterprise Linux as of version 3 + </para> + </listitem> + + <listitem> + <para> + SUSE and openSUSE Linux as of version 9 + </para> + </listitem> + + <listitem> + <para> + Ubuntu as of version 5.10 + </para> + </listitem> + + </itemizedlist> + + <para> + Many other distributions are known to work with the Guest + Additions. + </para> + + <para> + The version of the Linux kernel supplied by default in SUSE and + openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 + (server edition) contains a bug which can cause it to crash + during startup when it is run in a virtual machine. The Guest + Additions work in those distributions. + </para> + + <para> + Note that some Linux distributions already come with all or part + of the &product-name; Guest Additions. You may choose to keep + the distribution's version of the Guest Additions but these are + often not up to date and limited in functionality, so we + recommend replacing them with the Guest Additions that come with + &product-name;. The &product-name; Linux Guest Additions + installer tries to detect an existing installation and replace + them but depending on how the distribution integrates the Guest + Additions, this may require some manual interaction. It is + highly recommended to take a snapshot of the virtual machine + before replacing preinstalled Guest Additions. + </para> + + <sect3 id="additions-linux-install"> + + <title>Installing the Linux Guest Additions</title> + + <para> + The &product-name; Guest Additions for Linux are provided on + the same virtual CD-ROM file as the Guest Additions for + Windows. See <xref linkend="mountingadditionsiso"/>. They also + come with an installation program that guides you through the + setup process. However, due to the significant differences + between Linux distributions, installation may be slightly more + complex when compared to Windows. + </para> + + <para> + Installation generally involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Before installing the Guest Additions, you prepare your + guest system for building external kernel modules. This + works as described in + <xref linkend="externalkernelmodules" />, except that this + step must be performed in your Linux + <emphasis>guest</emphasis> instead of on a Linux host + system. + </para> + + <para> + If you suspect that something has gone wrong, check that + your guest is set up correctly and run the following + command as root: + </para> + +<screen>rcvboxadd setup</screen> + </listitem> + + <listitem> + <para> + Insert the + <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD + file into your Linux guest's virtual CD-ROM drive, as + described for a Windows guest in + <xref linkend="mountingadditionsiso" />. + </para> + </listitem> + + <listitem> + <para> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </para> + +<screen>sh ./VBoxLinuxAdditions.run</screen> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-linux-graphics-mouse"> + + <title>Graphics and Mouse Integration</title> + + <para> + In Linux and Oracle Solaris guests, &product-name; graphics + and mouse integration goes through the X Window System. + &product-name; can use the X.Org variant of the system, or + XFree86 version 4.3 which is identical to the first X.Org + release. During the installation process, the X.Org display + server will be set up to use the graphics and mouse drivers + which come with the Guest Additions. + </para> + + <para> + After installing the Guest Additions into a fresh installation + of a supported Linux distribution or Oracle Solaris system, + many unsupported systems will work correctly too, the guest's + graphics mode will change to fit the size of the + &product-name; window on the host when it is resized. You can + also ask the guest system to switch to a particular resolution + by sending a video mode hint using the + <command>VBoxManage</command> tool. + </para> + + <para> + Multiple guest monitors are supported in guests using the + X.Org server version 1.3, which is part of release 7.3 of the + X Window System version 11, or a later version. The layout of + the guest screens can be adjusted as needed using the tools + which come with the guest operating system. + </para> + + <para> + If you want to understand more about the details of how the + X.Org drivers are set up, in particular if you wish to use + them in a setting which our installer does not handle + correctly, see <xref linkend="guestxorgsetup" />. + </para> + + </sect3> + + <sect3 id="additions-linux-updating"> + + <title>Updating the Linux Guest Additions</title> + + <para> + The Guest Additions can simply be updated by going through the + installation procedure again with an updated CD-ROM image. + This will replace the drivers with updated versions. You + should reboot after updating the Guest Additions. + </para> + + </sect3> + + <sect3 id="additions-linux-uninstall"> + + <title>Uninstalling the Linux Guest Additions</title> + + <para> + If you have a version of the Guest Additions installed on your + virtual machine and wish to remove it without installing new + ones, you can do so by inserting the Guest Additions CD image + into the virtual CD-ROM drive as described above. Then run the + installer for the current Guest Additions with the + <computeroutput>uninstall</computeroutput> parameter from the + path that the CD image is mounted on in the guest, as follows: + </para> + +<screen>sh ./VBoxLinuxAdditions.run uninstall</screen> + + <para> + While this will normally work without issues, you may need to + do some manual cleanup of the guest in some cases, especially + of the XFree86Config or xorg.conf file. In particular, if the + Additions version installed or the guest operating system were + very old, or if you made your own changes to the Guest + Additions setup after you installed them. + </para> + + <para> + You can uninstall the Additions as follows: + </para> + +<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen> + + <para> + Replace + <computeroutput>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></computeroutput> + with the correct Guest Additions installation directory. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-solaris"> + + <title>Guest Additions for Oracle Solaris</title> + + <para> + Like the Windows Guest Additions, the &product-name; Guest + Additions for Oracle Solaris take the form of a set of device + drivers and system applications which may be installed in the + guest operating system. + </para> + + <para> + The following Oracle Solaris distributions are officially + supported: + </para> + + <itemizedlist> + + <listitem> + <para> + Oracle Solaris 11, including Oracle Solaris 11 Express + </para> + </listitem> + + <listitem> + <para> + Oracle Solaris 10 4/08 and later + </para> + </listitem> + + </itemizedlist> + + <para> + Other distributions may work if they are based on comparable + software releases. + </para> + + <sect3 id="additions-solaris-install"> + + <title>Installing the Oracle Solaris Guest Additions</title> + + <para> + The &product-name; Guest Additions for Oracle Solaris are + provided on the same ISO CD-ROM as the Additions for Windows + and Linux. They come with an installation program that guides + you through the setup process. + </para> + + <para> + Installation involves the following steps: + </para> + + <orderedlist> + + <listitem> + <para> + Mount the + <computeroutput>VBoxGuestAdditions.iso</computeroutput> + file as your Oracle Solaris guest's virtual CD-ROM drive, + exactly the same way as described for a Windows guest in + <xref + linkend="mountingadditionsiso" />. + </para> + + <para> + If the CD-ROM drive on the guest does not get mounted, as + seen with some versions of Oracle Solaris 10, run the + following command as root: + </para> + +<screen>svcadm restart volfs</screen> + </listitem> + + <listitem> + <para> + Change to the directory where your CD-ROM drive is mounted + and run the following command as root: + </para> + +<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen> + </listitem> + + <listitem> + <para> + Choose <emphasis role="bold">1</emphasis> and confirm + installation of the Guest Additions package. After the + installation is complete, log out and log in to X server + on your guest, to activate the X11 Guest Additions. + </para> + </listitem> + + </orderedlist> + + </sect3> + + <sect3 id="additions-solaris-uninstall"> + + <title>Uninstalling the Oracle Solaris Guest Additions</title> + + <para> + The Oracle Solaris Guest Additions can be safely removed by + removing the package from the guest. Open a root terminal + session and run the following command: + </para> + +<screen>pkgrm SUNWvboxguest</screen> + + </sect3> + + <sect3 id="additions-solaris-updating"> + + <title>Updating the Oracle Solaris Guest Additions</title> + + <para> + The Guest Additions should be updated by first uninstalling + the existing Guest Additions and then installing the new ones. + Attempting to install new Guest Additions without removing the + existing ones is not possible. + </para> + + </sect3> + + </sect2> + + <sect2 id="additions-os2"> + + <title>Guest Additions for OS/2</title> + + <para> + &product-name; also ships with a set of drivers that improve + running OS/2 in a virtual machine. Due to restrictions of OS/2 + itself, this variant of the Guest Additions has a limited + feature set. See <xref + linkend="KnownIssues" /> for + details. + </para> + + <para> + The OS/2 Guest Additions are provided on the same ISO CD-ROM as + those for the other platforms. Mount the ISO in OS/2 as + described previously. The OS/2 Guest Additions are located in + the directory <computeroutput>\OS2</computeroutput>. + </para> + + <para> + We do not provide an automatic installer at this time. See the + <computeroutput>readme.txt</computeroutput> file in the CD-ROM + directory, which describes how to install the OS/2 Guest + Additions manually. + </para> + + </sect2> + + </sect1> + + <sect1 id="sharedfolders"> + + <title>Shared Folders</title> + + <para> + With the <emphasis>shared folders</emphasis> feature of + &product-name;, you can access files of your host system from + within the guest system. This is similar to how you would use + network shares in Windows networks, except that shared folders do + not require networking, only the Guest Additions. Shared folders + are supported with Windows 2000 or later, Linux, and Oracle + Solaris guests. &product-name; release 6.0 includes experimental + support for Mac OS X and OS/2 guests. + </para> + + <para> + Shared folders physically reside on the <emphasis>host</emphasis> + and are then shared with the guest, which uses a special file + system driver in the Guest Additions to talk to the host. For + Windows guests, shared folders are implemented as a pseudo-network + redirector. For Linux and Oracle Solaris guests, the Guest + Additions provide a virtual file system. + </para> + + <para> + To share a host folder with a virtual machine in &product-name;, + you must specify the path of the folder and choose a + <emphasis>share name</emphasis> that the guest can use to access + the shared folder. This happens on the host. In the guest you can + then use the share name to connect to it and access files. + </para> + + <para> + There are several ways in which shared folders can be set up for a + virtual machine: + </para> + + <itemizedlist> + + <listitem> + <para> + In the window of a running VM, you select + <emphasis role="bold">Shared Folders</emphasis> from the + <emphasis role="bold">Devices</emphasis> menu, or click on the + folder icon on the status bar in the bottom right corner. + </para> + </listitem> + + <listitem> + <para> + If a VM is not currently running, you can configure shared + folders in the virtual machine's + <emphasis role="bold">Settings</emphasis> dialog. + </para> + </listitem> + + <listitem> + <para> + From the command line, you can create shared folders using + <command>VBoxManage</command>, as follows: + </para> + +<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen> + + <para> + See <xref linkend="vboxmanage-sharedfolder" />. + </para> + </listitem> + + </itemizedlist> + + <para> + There are two types of shares: + </para> + + <itemizedlist> + + <listitem> + <para> + Permanent shares, that are saved with the VM settings. + </para> + </listitem> + + <listitem> + <para> + Transient shares, that are added at runtime and disappear when + the VM is powered off. These can be created using a checkbox + in the VirtualBox Manager, or by using the + <computeroutput>--transient</computeroutput> option of the + <command>VBoxManage sharedfolder add</command> command. + </para> + </listitem> + + </itemizedlist> + + <para> + Shared folders can either be read-write or read-only. This means + that the guest is either allowed to both read and write, or just + read files on the host. By default, shared folders are read-write. + Read-only folders can be created using a checkbox in the + VirtualBox Manager, or with the + <computeroutput>--readonly</computeroutput> option of the + <command>VBoxManage sharedfolder add</command> command. + </para> + + <para> + &product-name; shared folders also support symbolic links, also + called <emphasis>symlinks</emphasis>, under the following + conditions: + </para> + + <itemizedlist> + + <listitem> + <para> + The host operating system must support symlinks. For example, + a Mac OS X, Linux, or Oracle Solaris host is required. + </para> + </listitem> + + <listitem> + <para> + Currently only Linux and Oracle Solaris Guest Additions + support symlinks. + </para> + </listitem> + + <listitem> + <para> + For security reasons the guest OS is not allowed to create + symlinks by default. If you trust the guest OS to not abuse + the functionality, you can enable creation of symlinks for a + shared folder as follows: + </para> + +<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen> + </listitem> + + </itemizedlist> + + <sect2 id="sf_mount_manual"> + + <title>Manual Mounting</title> + + <para> + You can mount the shared folder from inside a VM, in the same + way as you would mount an ordinary network share: + </para> + + <itemizedlist> + + <listitem> + <para> + In a Windows guest, shared folders are browseable and + therefore visible in Windows Explorer. To attach the host's + shared folder to your Windows guest, open Windows Explorer + and look for the folder in <emphasis role="bold">My + Networking Place</emphasis>s, <emphasis role="bold">Entire + Network</emphasis>, <emphasis role="bold">&product-name; + Shared Folders</emphasis>. By right-clicking on a shared + folder and selecting <emphasis role="bold">Map Network + Drive</emphasis> from the menu that pops up, you can assign + a drive letter to that shared folder. + </para> + + <para> + Alternatively, on the Windows command line, use the + following command: + </para> + +<screen>net use x: \\vboxsvr\sharename</screen> + + <para> + While <computeroutput>vboxsvr</computeroutput> is a fixed + name, note that <computeroutput>vboxsrv</computeroutput> + would also work, replace <replaceable>x:</replaceable> with + the drive letter that you want to use for the share, and + <replaceable>sharename</replaceable> with the share name + specified with <command>VBoxManage</command>. + </para> + </listitem> + + <listitem> + <para> + In a Linux guest, use the following command: + </para> + +<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen> + + <para> + To mount a shared folder during boot, add the following + entry to <computeroutput>/etc/fstab</computeroutput>: + </para> + +<screen>sharename mountpoint vboxsf defaults 0 0</screen> + </listitem> + + <listitem> + <para> + In a Oracle Solaris guest, use the following command: + </para> + +<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen> + + <para> + Replace <replaceable>sharename</replaceable>, use a + lowercase string, with the share name specified with + <command>VBoxManage</command> or the GUI. Replace + <replaceable>mountpoint</replaceable> with the path where + you want the share to be mounted on the guest, such as + <computeroutput>/mnt/share</computeroutput>. The usual mount + rules apply. For example, create this directory first if it + does not exist yet. + </para> + + <para> + Here is an example of mounting the shared folder for the + user jack on Oracle Solaris: + </para> + +<screen>$ id +uid=5000(jack) gid=1(other) +$ mkdir /export/home/jack/mount +$ pfexec mount -F vboxfs -o uid=5000,gid=1 jackshare /export/home/jack/mount +$ cd ~/mount +$ ls +sharedfile1.mp3 sharedfile2.txt +$</screen> + + <para> + Beyond the standard options supplied by the + <command>mount</command> command, the following are + available: + </para> + +<screen>iocharset CHARSET</screen> + + <para> + This option sets the character set used for I/O operations. + Note that on Linux guests, if the + <computeroutput>iocharset</computeroutput> option is not + specified, then the Guest Additions driver will attempt to + use the character set specified by the CONFIG_NLS_DEFAULT + kernel option. If this option is not set either, then UTF-8 + is used. + </para> + +<screen>convertcp CHARSET</screen> + + <para> + This option specifies the character set used for the shared + folder name. This is UTF-8 by default. + </para> + + <para> + The generic mount options, documented in the + <computeroutput>mount</computeroutput> manual page, apply + also. Especially useful are the options + <computeroutput>uid</computeroutput>, + <computeroutput>gid</computeroutput> and + <computeroutput>mode</computeroutput>, as they can allow + access by normal users in read/write mode, depending on the + settings, even if root has mounted the filesystem. + </para> + </listitem> + + <listitem> + <para> + In an OS/2 guest, use the <command>VBoxControl</command> + command to manage shared folders. For example: + </para> + +<screen>VBoxControl sharedfolder use D: MyShareName +VBoxControl sharedfolder unuse D: +VBoxControl sharedfolder list</screen> + + <para> + As with Windows guests, shared folders can also be accessed + via UNC using <computeroutput>\\VBoxSF\</computeroutput>, + <computeroutput>\\VBoxSvr\</computeroutput> or + <computeroutput>\\VBoxSrv\</computeroutput> as the server + name and the shared folder name as + <replaceable>sharename</replaceable>. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="sf_mount_auto"> + + <title>Automatic Mounting</title> + + <para> + &product-name; provides the option to mount shared folders + automatically. When automatic mounting is enabled for a shared + folder, the Guest Additions service will mount it for you + automatically. For Windows or OS/2, a preferred drive letter can + also be specified. For Linux or Oracle Solaris, a mount point + directory can also be specified. + </para> + + <para> + If a drive letter or mount point is not specified, or is in use + already, an alternative location is found by the Guest Additions + service. The service searches for an alternative location + depending on the guest OS, as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows and OS/2 guests.</emphasis> + Search for a free drive letter, starting at + <computeroutput>Z:</computeroutput>. If all drive letters + are assigned, the folder is not mounted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Linux and Oracle Solaris + guests.</emphasis> Folders are mounted under the + <computeroutput>/media</computeroutput> directory. The + folder name is normalized (no spaces, slashes or colons) and + is prefixed with <computeroutput>sf_</computeroutput>. + </para> + + <para> + For example, if you have a shared folder called + <computeroutput>myfiles</computeroutput>, it will appear as + <computeroutput>/media/sf_myfiles</computeroutput> in the + guest. + </para> + + <para> + The guest properties + <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput> + and the more generic + <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput> + can be used to override the automatic mount directory and + prefix. See <xref linkend="guestadd-guestprops" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Access to an automatically mounted shared folder is granted to + everyone in a Windows guest, including the guest user. For Linux + and Oracle Solaris guests, access is restricted to members of + the group <computeroutput>vboxsf</computeroutput> and the + <computeroutput>root</computeroutput> user. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-dnd"> + + <title>Drag and Drop</title> + + <para> + &product-name; enables you to drag and drop content from the host + to the guest, and vice versa. For this to work the latest Guest + Additions must be installed on the guest. + </para> + + <para> + Drag and drop transparently allows copying or opening files, + directories, and even certain clipboard formats from one end to + the other. For example, from the host to the guest or from the + guest to the host. You then can perform drag and drop operations + between the host and a VM, as it would be a native drag and drop + operation on the host OS. + </para> + + <para> + At the moment drag and drop is implemented for Windows-based and + X-Windows-based systems, both on the host and guest side. As + X-Windows supports many different drag and drop protocols only the + most common one, XDND, is supported for now. Applications using + other protocols, such as Motif or OffiX, will not be recognized by + &product-name;. + </para> + + <para> + In the context of using drag and drop, the origin of the data is + called the <emphasis>source</emphasis>. That is, where the actual + data comes from and is specified. The <emphasis>target</emphasis> + specifies where the data from the source should go to. + Transferring data from the source to the target can be done in + various ways, such as copying, moving, or linking. + </para> + + <note> + <para> + At the moment only copying of data is supported. Moving or + linking is not yet implemented. + </para> + </note> + + <para> + When transferring data from the host to the guest OS, the host in + this case is the source, whereas the guest OS is the target. + However, when transferring data from the guest OS to the host, the + guest OS this time became the source and the host is the target. + </para> + + <para> + For security reasons drag and drop can be configured at runtime on + a per-VM basis either using the <emphasis role="bold">Drag and + Drop</emphasis> menu item in the + <emphasis role="bold">Devices</emphasis> menu of the virtual + machine, as shown below, or the <command>VBoxManage</command> + command. + </para> + + <figure id="fig-drag-drop-options"> + <title>Drag and Drop Menu Options</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/dnd-modes.png" + width="10cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The following drag and drop modes are available: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Disabled.</emphasis> Disables the drag + and drop feature entirely. This is the default when creating a + new VM. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Host To Guest.</emphasis> Enables drag + and drop operations from the host to the guest only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Guest To Host.</emphasis> Enables drag + and drop operations from the guest to the host only. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Bidirectional.</emphasis> Enables drag + and drop operations in both directions: from the host to the + guest, and from the guest to the host. + </para> + </listitem> + + </itemizedlist> + + <note> + <para> + Drag and drop support depends on the frontend being used. At the + moment, only the VirtualBox Manager frontend provides this + functionality. + </para> + </note> + + <para> + To use the <command>VBoxManage</command> command to control the + current drag and drop mode, see <xref linkend="vboxmanage" />. The + <command>modifyvm</command> and <command>controlvm</command> + commands enable setting of a VM's current drag and drop mode from + the command line. + </para> + + <sect2 id="guestadd-dnd-formats"> + + <title>Supported Formats</title> + + <para> + As &product-name; can run on a variety of host operating systems + and also supports a wide range of guests, certain data formats + must be translated after transfer. This is so that the target + operating system, which receiving the data, is able to handle + them in an appropriate manner. + </para> + + <note> + <para> + When dragging files no data conversion is done in any way. For + example, when transferring a file from a Linux guest to a + Windows host the Linux-specific line endings are not converted + to Windows line endings. + </para> + </note> + + <para> + The following formats are handled by the &product-name; drag and + drop service: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Plain text:</emphasis> From + applications such as text editors, internet browsers and + terminal windows. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Files:</emphasis> From file managers + such as Windows Explorer, Nautilus, and Finder. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Directories:</emphasis> For + directories, the same formats apply as for files. + </para> + </listitem> + + </itemizedlist> + + </sect2> + + <sect2 id="guestadd-dnd-limitations"> + + <title>Known Limitations</title> + + <para> + The following limitations are known for drag and drop: + </para> + + <para> + On Windows hosts, dragging and dropping content between + UAC-elevated (User Account Control) programs and + non-UAC-elevated programs is not allowed. If you start + &product-name; with Administrator privileges then drag and drop + will not work with Windows Explorer, which runs with regular + user privileges by default. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-video"> + + <title>Hardware-Accelerated Graphics</title> + + <sect2 id="guestadd-3d"> + + <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title> + + <para> + The &product-name; Guest Additions contain experimental hardware + 3D support for Windows, Linux, and Oracle Solaris guests. + </para> + + <para> + With this feature, if an application inside your virtual machine + uses 3D features through the OpenGL or Direct3D 8/9 programming + interfaces, instead of emulating them in software, which would + be slow, &product-name; will attempt to use your host's 3D + hardware. This works for all supported host platforms, provided + that your host operating system can make use of your accelerated + 3D hardware in the first place. + </para> + + <para> + The 3D acceleration feature currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + It is only available for certain Windows, Linux, and Oracle + Solaris guests. In particular: + </para> + + <itemizedlist> + + <listitem> + <para> + 3D acceleration with Windows guests requires Windows + 2000, Windows XP, Vista, or Windows 7. Apart from on + Windows 2000 guests, both OpenGL and Direct3D 8/9 are + supported on an experimental basis. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Linux requires kernel 2.6.27 or later, as well + as X.org server version 1.5 or later. Ubuntu 10.10 and + Fedora 14 have been tested and confirmed as working. + </para> + </listitem> + + <listitem> + <para> + OpenGL on Oracle Solaris guests requires X.org server + version 1.5 or later. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + The Guest Additions must be installed. + </para> + + <note> + <para> + For the basic Direct3D acceleration to work in a Windows + Guest, &product-name; needs to replace Windows system + files in the virtual machine. As a result, the Guest + Additions installation program offers Direct3D + acceleration as an option that must be explicitly enabled. + Also, you must install the Guest Additions in Safe Mode. + This does <emphasis>not</emphasis> apply to the WDDM + Direct3D video driver available for Windows Vista and + later. See <xref linkend="KnownIssues" /> for details. + </para> + </note> + </listitem> + + <listitem> + <para> + Because 3D support is still experimental at this time, it is + disabled by default and must be <emphasis>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + + <note> + <para> + Untrusted guest systems should not be allowed to use the + 3D acceleration features of &product-name;, just as + untrusted host software should not be allowed to use 3D + acceleration. Drivers for 3D hardware are generally too + complex to be made properly secure and any software which + is allowed to access them may be able to compromise the + operating system running them. In addition, enabling 3D + acceleration gives the guest direct access to a large body + of additional program code in the &product-name; host + process which it might conceivably be able to use to crash + the virtual machine. + </para> + </note> + </listitem> + + </itemizedlist> + + <para> + To enable Aero theme support, the &product-name; WDDM video + driver must be installed, which is available with the Guest + Additions installation. The WDDM driver is not installed by + default for Vista and Windows 7 guest and must be + <emphasis>manually selected</emphasis> in the Guest Additions + installer by clicking <emphasis role="bold">No</emphasis> in the + <emphasis role="bold">Would You Like to Install Basic Direct3D + Support</emphasis> dialog displayed when the Direct3D feature is + selected. + </para> + + <para> + The Aero theme is not enabled by default. To enable it, do the + following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Windows Vista guests:</emphasis> + Right-click on the desktop and select + <emphasis role="bold">Personalize</emphasis>, then select + <emphasis role="bold">Windows Color and + Appearance</emphasis> in the + <emphasis role="bold">Personalization</emphasis> window. In + the <emphasis role="bold">Appearance Settings</emphasis> + dialog, select <emphasis role="bold">Windows Aero</emphasis> + and click <emphasis role="bold">OK</emphasis>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Windows 7 guests:</emphasis> + Right-click on the desktop and select + <emphasis role="bold">Personalize</emphasis>. Select any + Aero theme in the + <emphasis role="bold">Personalization</emphasis> window. + </para> + </listitem> + + </itemizedlist> + + <para> + Technically, &product-name; implements this by installing an + additional hardware 3D driver inside your guest when the Guest + Additions are installed. This driver acts as a hardware 3D + driver and reports to the guest operating system that the + virtual hardware is capable of 3D hardware acceleration. When an + application in the guest then requests hardware acceleration + through the OpenGL or Direct3D programming interfaces, these are + sent to the host through a special communication tunnel + implemented by &product-name;, and then the + <emphasis>host</emphasis> performs the requested 3D operation + using the host's programming interfaces. + </para> + + </sect2> + + <sect2 id="guestadd-2d"> + + <title>Hardware 2D Video Acceleration for Windows Guests</title> + + <para> + The &product-name; Guest Additions contain experimental hardware + 2D video acceleration support for Windows guests. + </para> + + <para> + With this feature, if an application such as a video player + inside your Windows VM uses 2D video overlays to play a movie + clip, then &product-name; will attempt to use your host's video + acceleration hardware instead of performing overlay stretching + and color conversion in software, which would be slow. This + currently works for Windows, Linux and Mac OS X host platforms, + provided that your host operating system can make use of 2D + video acceleration in the first place. + </para> + + <para> + Hardware 2D video acceleration currently has the following + preconditions: + </para> + + <itemizedlist> + + <listitem> + <para> + Only available for Windows guests, running Windows XP or + later. + </para> + </listitem> + + <listitem> + <para> + Guest Additions must be installed. + </para> + </listitem> + + <listitem> + <para> + Because 2D support is still experimental at this time, it is + disabled by default and must be <emphasis>manually + enabled</emphasis> in the VM settings. See + <xref linkend="settings-display" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Technically, &product-name; implements this by exposing video + overlay DirectDraw capabilities in the Guest Additions video + driver. The driver sends all overlay commands to the host + through a special communication tunnel implemented by + &product-name;. On the host side, OpenGL is then used to + implement color space transformation and scaling + </para> + + </sect2> + + </sect1> + + <sect1 id="seamlesswindows"> + + <title>Seamless Windows</title> + + <para> + With the <emphasis>seamless windows</emphasis> feature of + &product-name;, you can have the windows that are displayed within + a virtual machine appear side by side next to the windows of your + host. This feature is supported for the following guest operating + systems, provided that the Guest Additions are installed: + </para> + + <itemizedlist> + + <listitem> + <para> + Windows guests. Support was added in &product-name; 1.5. + </para> + </listitem> + + <listitem> + <para> + Supported Linux or Oracle Solaris guests running the X Window + System. Support was added with &product-name; 1.6. + </para> + </listitem> + + </itemizedlist> + + <para> + After seamless windows are enabled, &product-name; suppresses the + display of the desktop background of your guest, allowing you to + run the windows of your guest operating system seamlessly next to + the windows of your host. + </para> + + <figure id="fig-seamless-windows"> + <title>Seamless Windows on a Host Desktop</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/seamless.png" width="14cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + To enable seamless mode, after starting the virtual machine, press + the <emphasis role="bold">Host key + L</emphasis>. The Host key is + normally the right control key. This will enlarge the size of the + VM's display to the size of your host screen and mask out the + guest operating system's background. To disable seamless windows + and go back to the normal VM display, press the Host key + L + again. + </para> + + </sect1> + + <sect1 id="guestadd-guestprops"> + + <title>Guest Properties</title> + + <para> + &product-name; enables requests of some properties from a running + guest, provided that the &product-name; Guest Additions are + installed and the VM is running. This provides the following + advantages: + </para> + + <itemizedlist> + + <listitem> + <para> + A number of predefined VM characteristics are automatically + maintained by &product-name; and can be retrieved on the host. + For example, to monitor VM performance and statistics. + </para> + </listitem> + + <listitem> + <para> + Arbitrary string data can be exchanged between guest and host. + This works in both directions. + </para> + </listitem> + + </itemizedlist> + + <para> + To accomplish this, &product-name; establishes a private + communication channel between the &product-name; Guest Additions + and the host, and software on both sides can use this channel to + exchange string data for arbitrary purposes. Guest properties are + simply string keys to which a value is attached. They can be set, + or written to, by either the host and the guest. They can also be + read from both sides. + </para> + + <para> + In addition to establishing the general mechanism of reading and + writing values, a set of predefined guest properties is + automatically maintained by the &product-name; Guest Additions to + allow for retrieving interesting guest data such as the guest's + exact operating system and service pack level, the installed + version of the Guest Additions, users that are currently logged + into the guest OS, network statistics and more. These predefined + properties are all prefixed with + <computeroutput>/VirtualBox/</computeroutput> and organized into a + hierarchical tree of keys. + </para> + + <para> + Some of this runtime information is shown when you select + <emphasis role="bold">Session Information Dialog</emphasis> from a + virtual machine's <emphasis role="bold">Machine</emphasis> menu. + </para> + + <para> + A more flexible way to use this channel is with the + <command>VBoxManage guestproperty</command> command. See + <xref linkend="vboxmanage-guestproperty" />. For example, to have + <emphasis>all</emphasis> the available guest properties for a + given running VM listed with their respective values, use this + command: + </para> + +<screen>$ VBoxManage guestproperty enumerate "Windows Vista III" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Name: /VirtualBox/GuestInfo/OS/Product, value: Windows Vista Business Edition, + timestamp: 1229098278843087000, flags: +Name: /VirtualBox/GuestInfo/OS/Release, value: 6.0.6001, + timestamp: 1229098278950553000, flags: +Name: /VirtualBox/GuestInfo/OS/ServicePack, value: 1, + timestamp: 1229098279122627000, flags: +Name: /VirtualBox/GuestAdd/InstallDir, + value: C:/Program Files/Oracle/VirtualBox + Guest Additions, timestamp: 1229098279269739000, flags: +Name: /VirtualBox/GuestAdd/Revision, value: 40720, + timestamp: 1229098279345664000, flags: +Name: /VirtualBox/GuestAdd/Version, value: <replaceable>version-number</replaceable>, + timestamp: 1229098279479515000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279651731000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279804835000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279880611000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279882618000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279883195000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279885027000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279886838000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279890600000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279893056000, flags: +Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720, + timestamp: 1229098279895767000, flags: +Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1, + timestamp: 1229099826317660000, flags: +Name: /VirtualBox/GuestInfo/OS/NoLoggedInUsers, value: false, + timestamp: 1229098455580553000, flags: +Name: /VirtualBox/GuestInfo/Net/Count, value: 1, + timestamp: 1229099826299785000, flags: +Name: /VirtualBox/HostInfo/GUI/LanguageID, value: C, + timestamp: 1229098151272771000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/IP, value: 192.168.2.102, + timestamp: 1229099826300088000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/Broadcast, value: 255.255.255.255, + timestamp: 1229099826300220000, flags: +Name: /VirtualBox/GuestInfo/Net/0/V4/Netmask, value: 255.255.255.0, + timestamp: 1229099826300350000, flags: +Name: /VirtualBox/GuestInfo/Net/0/Status, value: Up, + timestamp: 1229099826300524000, flags: +Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username, + timestamp: 1229099826317386000, flags:</screen> + + <para> + To query the value of a single property, use the + <computeroutput>get</computeroutput> subcommand as follows: + </para> + +<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product" +VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Value: Windows Vista Business Edition</screen> + + <para> + To add or change guest properties from the guest, use the tool + <computeroutput>VBoxControl</computeroutput>. This tool is + included in the Guest Additions of &product-name; 2.2 or later. + When started from a Linux guest, this tool requires root + privileges for security reasons: + </para> + +<screen>$ sudo VBoxControl guestproperty enumerate +VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable> +(C) 2005-2018 Oracle Corporation +All rights reserved. + +Name: /VirtualBox/GuestInfo/OS/Release, value: 2.6.28-18-generic, + timestamp: 1265813265835667000, flags: <NULL> +Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010, + timestamp: 1265813265836305000, flags: <NULL> + ...</screen> + + <para> + For more complex needs, you can use the &product-name; programming + interfaces. See <xref linkend="VirtualBoxAPI" />. + </para> + + <sect2 id="guestadd-guestprops-waits"> + + <title>Using Guest Properties to Wait on VM Events</title> + + <para> + The properties + <computeroutput>/VirtualBox/HostInfo/VBoxVer</computeroutput>, + <computeroutput>/VirtualBox/HostInfo/VBoxVerExt</computeroutput> + or <computeroutput>/VirtualBox/HostInfo/VBoxRev</computeroutput> + can be waited on to detect that the VM state was restored from + saved state or snapshot: + </para> + +<screen>$ VBoxControl guestproperty wait /VirtualBox/HostInfo/VBoxVer</screen> + + <para> + Similarly the + <computeroutput>/VirtualBox/HostInfo/ResumeCounter</computeroutput> + can be used to detect that a VM was resumed from the paused + state or saved state. + </para> + + </sect2> + + </sect1> + + <sect1 id="guestadd-gc-file-manager"> + + <title>Guest Control File Manager</title> + + <para> + The Guest Control File Manager is a feature of the Guest Additions + that enables easy copying and moving of files between a guest and + the host system. Other file management operations provide support + to create new folders and to rename or delete files. + </para> + + <figure id="fig-guest-control-fm"> + <title>Guest Control File Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/guest-fm.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The Guest Control File Manager works by mounting the host file + system. Guest users must authenticate and create a guest session + before they can transfer files. + </para> + + <sect2 id="guestadd-gc-file-manager-using"> + + <title>Using the Guest Control File Manager</title> + + <para> + The following steps describe how to use the Guest Control File + Manager. + </para> + + <orderedlist> + + <listitem> + <para> + Open the Guest Control File Manager. + </para> + + <para> + In the guest VM, select + <emphasis role="bold">Machine</emphasis>, + <emphasis role="bold">File Manager</emphasis>. + </para> + + <para> + The left pane shows the files on the host system. + </para> + </listitem> + + <listitem> + <para> + Create a guest session. + </para> + + <para> + At the bottom of the Guest Control File Manager, enter + authentication credentials for a user on the guest system. + </para> + + <para> + Click <emphasis role="bold">Create Session</emphasis>. + </para> + + <para> + The contents of the guest VM file system appears in the + right pane of the Guest Control File Manager. + </para> + </listitem> + + <listitem> + <para> + Transfer files between the guest and the host system by + using the move and copy file transfer icons. + </para> + + <para> + You can copy and move files from a guest to the host system + or from the host system to the guest. + </para> + </listitem> + + <listitem> + <para> + Close the Guest Control File Manager. + </para> + + <para> + Click <emphasis role="bold">Close</emphasis> to end the + guest session. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="guestadd-guestcontrol"> + + <title>Guest Control of Applications</title> + + <para> + The Guest Additions enable starting of applications inside a VM + from the host system. + </para> + + <para> + For this to work, the application needs to be installed inside the + guest. No additional software needs to be installed on the host. + Additionally, text mode output to stdout and stderr can be shown + on the host for further processing. There are options to specify + user credentials and a timeout value, in milliseconds, to limit + the time the application is able to run. + </para> + + <para> + This feature can be used to automate deployment of software within + the guest. + </para> + + <para> + The Guest Additions for Windows allow for automatic updating. This + applies for already installed Guest Additions version 4.0 or + later. Also, copying files from host to the guest as well as + remotely creating guest directories is available. + </para> + + <para> + To use these features, use the &product-name; command line. See + <xref linkend="vboxmanage-guestcontrol" />. + </para> + + </sect1> + + <sect1 id="guestadd-memory-usage"> + + <title>Memory Overcommitment</title> + + <para> + In server environments with many VMs, the Guest Additions can be + used to share physical host memory between several VMs. This + reduces the total amount of memory in use by the VMs. If memory + usage is the limiting factor and CPU resources are still + available, this can help with running more VMs on each host. + </para> + + <sect2 id="guestadd-balloon"> + + <title>Memory Ballooning</title> + + <para> + The Guest Additions can change the amount of host memory that a + VM uses, while the machine is running. Because of how this is + implemented, this feature is called <emphasis>memory + ballooning</emphasis>. + </para> + + <note> + <itemizedlist> + + <listitem> + <para> + &product-name; supports memory ballooning only on 64-bit + hosts. It is not supported on Mac OS X hosts. + </para> + </listitem> + + <listitem> + <para> + Memory ballooning does not work with large pages enabled. + To turn off large pages support for a VM, run + <computeroutput>VBoxManage modifyvm <VM name> + --largepages off</computeroutput> + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Normally, to change the amount of memory allocated to a virtual + machine, you have to shut down the virtual machine entirely and + modify its settings. With memory ballooning, memory that was + allocated for a virtual machine can be given to another virtual + machine without having to shut the machine down. + </para> + + <para> + When memory ballooning is requested, the &product-name; Guest + Additions, which run inside the guest, allocate physical memory + from the guest operating system on the kernel level and lock + this memory down in the guest. This ensures that the guest will + not use that memory any longer. No guest applications can + allocate it, and the guest kernel will not use it either. + &product-name; can then reuse this memory and give it to another + virtual machine. + </para> + + <para> + The memory made available through the ballooning mechanism is + only available for reuse by &product-name;. It is + <emphasis>not</emphasis> returned as free memory to the host. + Requesting balloon memory from a running guest will therefore + not increase the amount of free, unallocated memory on the host. + Effectively, memory ballooning is therefore a memory + overcommitment mechanism for multiple virtual machines while + they are running. This can be useful to temporarily start + another machine, or in more complicated environments, for + sophisticated memory management of many virtual machines that + may be running in parallel depending on how memory is used by + the guests. + </para> + + <para> + At this time, memory ballooning is only supported through + <command>VBoxManage</command>. Use the following command to + increase or decrease the size of the memory balloon within a + running virtual machine that has Guest Additions installed: + </para> + +<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen> + + <para> + where <replaceable>VM name</replaceable> is the name or UUID of + the virtual machine in question and <replaceable>n</replaceable> + is the amount of memory to allocate from the guest in megabytes. + See <xref + linkend="vboxmanage-controlvm" />. + </para> + + <para> + You can also set a default balloon that will automatically be + requested from the VM every time after it has started up with + the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --guestmemoryballoon n</screen> + + <para> + By default, no balloon memory is allocated. This is a VM + setting, like other <computeroutput>modifyvm</computeroutput> + settings, and therefore can only be set while the machine is + shut down. See <xref + linkend="vboxmanage-modifyvm" />. + </para> + + </sect2> + + <sect2 id="guestadd-pagefusion"> + + <title>Page Fusion</title> + + <para> + Whereas memory ballooning simply reduces the amount of RAM that + is available to a VM, Page Fusion works differently. It avoids + memory duplication between several similar running VMs. + </para> + + <para> + In a server environment running several similar VMs on the same + host, lots of memory pages are identical. For example, if the + VMs are using identical operating systems. &product-name;'s Page + Fusion technology can efficiently identify these identical + memory pages and share them between multiple VMs. + </para> + + <note> + <para> + &product-name; supports Page Fusion only on 64-bit hosts, and + it is not supported on Mac OS X hosts. Page Fusion currently + works only with Windows 2000 and later guests. + </para> + </note> + + <para> + The more similar the VMs on a given host are, the more + efficiently Page Fusion can reduce the amount of host memory + that is in use. It therefore works best if all VMs on a host run + identical operating systems, such as Windows XP Service Pack 2. + Instead of having a complete copy of each operating system in + each VM, Page Fusion identifies the identical memory pages in + use by these operating systems and eliminates the duplicates, + sharing host memory between several machines. This is called + <emphasis>deduplication</emphasis>. If a VM tries to modify a + page that has been shared with other VMs, a new page is + allocated again for that VM with a copy of the shared page. This + is called <emphasis>copy on write</emphasis>. All this is fully + transparent to the virtual machine. + </para> + + <para> + You may be familiar with this kind of memory overcommitment from + other hypervisor products, which call this feature + <emphasis>page sharing</emphasis> or <emphasis>same page + merging</emphasis>. However, Page Fusion differs significantly + from those other solutions, whose approaches have several + drawbacks: + </para> + + <itemizedlist> + + <listitem> + <para> + Traditional hypervisors scan <emphasis>all</emphasis> guest + memory and compute checksums, also called hashes, for every + single memory page. Then, they look for pages with identical + hashes and compare the entire content of those pages. If two + pages produce the same hash, it is very likely that the + pages are identical in content. This process can take rather + long, especially if the system is not idling. As a result, + the additional memory only becomes available after a + significant amount of time, such as hours or sometimes days. + Even worse, this kind of page sharing algorithm generally + consumes significant CPU resources and increases the + virtualization overhead by 10 to 20%. + </para> + + <para> + Page Fusion in &product-name; uses logic in the + &product-name; Guest Additions to quickly identify memory + cells that are most likely identical across VMs. It can + therefore achieve most of the possible savings of page + sharing almost immediately and with almost no overhead. + </para> + </listitem> + + <listitem> + <para> + Page Fusion is also much less likely to be confused by + identical memory that it will eliminate, just to learn + seconds later that the memory will now change and having to + perform a highly expensive and often service-disrupting + reallocation. + </para> + </listitem> + + </itemizedlist> + + <para> + At this time, Page Fusion can only be controlled with + <command>VBoxManage</command>, and only while a VM is shut down. + To enable Page Fusion for a VM, use the following command: + </para> + +<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen> + + <para> + You can observe Page Fusion operation using some metrics. + <computeroutput>RAM/VMM/Shared</computeroutput> shows the total + amount of fused pages, whereas the per-VM metric + <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will + return the amount of fused memory for a given VM. See + <xref + linkend="vboxmanage-metrics" /> for information on + how to query metrics. + </para> + + <note> + <para> + Enabling Page Fusion might indirectly increase the chances for + malicious guests to successfully attack other VMs running on + the same host. See <xref linkend="pot-insecure"/>. + </para> + </note> + + </sect2> + + </sect1> + +</chapter> |