7 Guest Additions

The Guest Additions are designed to be installed inside 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 Guest Operating Systems for details on the guest operating systems that Oracle provides premier support for.

The available Oracle VirtualBox Guest Additions are provided as a single CD-ROM image file called VBoxGuestAdditions.iso. This image file is located in the installation directory of Oracle VirtualBox. To install the Guest Additions for a particular OS, you mount this ISO file in your VM as a virtual CD-ROM and install from there.

You can also configure unattended installation of the Oracle VirtualBox Guest Additions when you create a new VM. See Configure Unattended Installation of Guest OS.

Introduction to Guest Additions

The Guest Additions offer the following features:

  • Mouse pointer integration. To overcome the limitations for mouse support described in Capturing and Releasing Keyboard and Mouse, 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 physical mouse driver on your host and moves the guest mouse pointer accordingly.

  • Shared folders. These provide an easy way to exchange files between the host and the guest. Much like ordinary Windows network shares, you can tell Oracle VirtualBox to treat a certain host directory as a shared folder, and Oracle VirtualBox will make it available to the guest operating system as a network share, irrespective of whether the guest actually has a network. See Shared Folders.

  • Better video support. While the virtual graphics card which Oracle VirtualBox emulates for any guest operating system provides all the basic features, the custom video drivers that are installed with the Guest Additions provide you with extra high and nonstandard video modes, as well as accelerated video performance.

    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 Display settings. See Resizing the VM's Window.

    If the Guest Additions are installed, 3D graphics for guest applications can be accelerated. See Hardware-Accelerated Graphics.

  • Seamless windows. 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 Seamless Windows.

  • Generic host/guest communication channels. 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 Guest Properties.

    Additionally, applications can be started in a guest from the host. See Guest Control of Applications.

  • Time synchronization. With the Guest Additions installed, Oracle VirtualBox can ensure that the guest's system time is better synchronized with that of the host.

    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.

    The Guest Additions will resynchronize the time regularly. See Tuning the Guest Additions Time Synchronization Parameters for how to configure the parameters of the time synchronization mechanism.

  • Shared clipboard. With the Guest Additions installed, the clipboard of the guest operating system can optionally be shared with your host operating system. See General Settings.

  • Drag and Drop. Guest Additions enable you to select an object, such as a file, from the host or guest and directly copy or open it on the guest or host. See General Settings.

  • Automated logins. Also called credentials passing. See Automated Guest Logins.

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

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

To disable this update check for the Guest Additions of a given virtual machine, set the value of its /VirtualBox/GuestAdd/CheckHostVersion guest property to 0. See Guest Properties.

Installing Guest Additions

These instructions apply to all OSs. For additional information, see Guest Additions for Windows, Guest Additions for Linux, Guest Additions for Oracle Solaris, or Guest Additions for OS/2.

Mount the Guest Additions ISO

  1. Start the virtual machine. The OS must be installed.

  2. From the Devices menu, choose Insert Guest Additions CD Image, which mounts the Guest Additions ISO file inside your VM.

  3. If this option is not available, or if you prefer to mount the ISO manually:

    1. From the Devices menu, choose Optical Drives, and then Choose/Create a Disk Image. This displays The Virtual Media Manager.

    2. In the Virtual Media Manager, click Add and browse your host file system for the VBoxGuestAdditions.iso file.

      • On a Windows host, this file is in the Oracle VirtualBox installation directory, usually in C:\Program files\Oracle\VirtualBox.

      • On a Linux host, this file is in the additions folder where you installed Oracle VirtualBox, usually /opt/VirtualBox/.

      • On Oracle Solaris hosts, this file is in the additions folder where you installed Oracle VirtualBox, usually /opt/VirtualBox.

    3. In the Virtual Media Manager, select the ISO file and click Add. This mounts the ISO file and presents it to your guest OS as a CD-ROM.

Run the Guest Additions Installer

  1. Mount the ISO as described in the previous task.

  2. Unless you have the Autostart feature disabled, or it is not supported, the OS will now autostart the Oracle VirtualBox Guest Additions installer from the Guest Additions ISO.

    If the Autostart feature has been turned off, choose VBox<OS>Additions.exe from the CD/DVD drive inside the guest to start the installer, where <OS> is Windows, Linux, OS2 or Solaris.

  3. Follow the instructions in the installer.

  4. Reboot the guest OS.

Guest Additions for Windows

The Oracle VirtualBox Windows Guest Additions are designed to be installed in a virtual machine running a Windows operating system. The Windows Guest Additions will run on VMs running these versions of Windows. See also Host and Guest Combinations.

Arm64 VMs

  • Microsoft Windows 11

x86 and x86_64 VMs

  • Microsoft Windows 11

  • Microsoft Windows Server 2022

  • Microsoft Windows 10 (all builds)

  • Microsoft Windows Server 2019

  • Microsoft Windows Server 2016

  • Microsoft Windows 8.1 (all editions)

  • Microsoft Windows Server 2012R2

  • Microsoft Windows 8 (all editions)

  • Microsoft Windows Server 2012

  • Microsoft Windows 7 (all editions)

  • Microsoft Windows Server 2008R2

  • Microsoft Windows Vista (all editions)

  • Microsoft Windows Server 2008

  • Microsoft Windows XP (any service pack)

  • Microsoft Windows Server 2003 (any service pack)

  • Microsoft Windows 2000 (any service pack)

  • Microsoft Windows NT 4.0 (any service pack)

Installing the Windows Guest Additions

Follow the steps in Installing Guest Additions.

Note:

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.

For Windows 8 and later, only the WDDM Direct3D video driver is available.

For completely unattended guest installations, you can specify a command line parameter to the install launcher: 

VBoxWindowsAdditions.exe /S

This automatically installs the right files and drivers for the corresponding platform, either 32-bit or 64-bit.

Note:

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

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

VBoxWindowsAdditions.exe /?
Updating the Windows Guest Additions

Windows Guest Additions can be updated by running the installation program again, or by selecting Devices, and then Upgrade Guest Additions... This replaces the previous Additions drivers with updated versions.

Alternatively, you can also open the Windows Device Manager and select Update Driver... for the following devices:

  • Oracle VirtualBox Graphics Adapter

  • Oracle VirtualBox System Device

For each, choose the option to provide your own driver, click Have Disk and navigate to the CD-ROM drive with the Guest Additions.

Installing Code Signing Certificates

To avoid popups when performing an unattended installation of the Oracle VirtualBox 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. If you do not do this, the installation will prompt you before the installation of each driver.

The certificates are stored for you if installing Guest Additions as part of the Windows unattended installation when creating a new VM. If you are automating the installation of Guest Additions yourself, you first need to install the code signing certificates on the VM.

Use the VBoxCertUtil.exe utility from the cert folder on the Guest Additions installation CD.

Note:

On some legacy Windows versions, such as Windows 2000 and Windows XP, the user intervention popups mentioned above are always displayed, even after importing the Oracle certificates.

  1. Log in as Administrator on the guest.

  2. Mount the Oracle VirtualBox Guest Additions ISO.

  3. Open a command line window on the guest and change to the cert folder on the Oracle VirtualBox Guest Additions CD.

  4. Run the following command:

    VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer

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

Automated Windows System Preparation

Microsoft offers a system preparation tool called Sysprep, to prepare a Windows system for deployment or redistribution. For most Windows versions, Sysprep is included in a default installation. Sysprep mainly consists of an executable called sysprep.exe which is invoked by the user to put the Windows installation into preparation mode.

The Guest Additions offer a way to launch a system preparation on the guest operating system in an automated way, controlled from the host system. See Guest Control of Applications for details of how to use this feature with the special identifier sysprep as the program to execute, along with the user name sysprep and password sysprep for the credentials. Sysprep is then started with the required system rights.

Note:

Specifying the location of sysprep.exe is not possible. Instead the following paths are used, based on the Windows release:

  • C:\sysprep\sysprep.exe for Windows XP and earlier

  • %WINDIR%\System32\sysprep\sysprep.exe for Windows Vista and later

The Guest Additions will automatically use the appropriate path to execute the system preparation tool.

Manual File Extraction

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

VBoxWindowsAdditions.exe /extract

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 VBoxWindowsAdditions-x86.exe or VBoxWindowsAdditions-amd64.exe with the /extract parameter.

Guest Additions for Linux

The Oracle VirtualBox Guest Additions for Linux are a set of device drivers and system applications that may be installed in the guest operating system. The Linux Guest Additions will run on VMs running these versions of Linux. See also Host and Guest Combinations.

Arm64 VMs

  • Oracle Linux 8 and later, including UEK kernels

x86 and x86_64 VMs

  • Oracle Linux 5 and later, including UEK kernels

  • Fedora Core 4 and later

  • Red Hat Enterprise Linux version 3 and later

  • SUSE and openSUSE Linux version 9 and later

  • Ubuntu version 5.10 and later

The guest additions may also work on other distributions.

Installing the Linux Guest Additions

To install the guest additions:

  1. Prepare your guest system for building external kernel modules. Follow the steps in The Oracle VirtualBox Kernel Modules, on your Linux VM instead of on a Linux host system.

  2. Insert the VBoxGuestAdditions.iso CD file into your Linux guest's virtual CD-ROM drive. See Installing Guest Additions.

  3. Change to the directory where your CD-ROM drive is mounted and run the following command as root:

    sh ./VBoxLinuxAdditions.run
  4. If you suspect that something has gone wrong, check that your VM is set up correctly and run the following command as root:
    rcvboxadd setup
    To check if drivers were loaded, and the versions of the loaded drivers match the installation version of the Guest Additions, run the following command as root: 
    rcvboxadd status-kernel
    To check if the VBoxService is running, run the following command as root: 
    rcvboxadd status-user
Manual Setup of Selected Guest Services on Linux

The Oracle VirtualBox Guest Additions contain several different drivers. If you do not want to configure them all, use the following command to install the Guest Additions: 

$ sh ./VBoxLinuxAdditions.run no_setup

After running this script, run the rcvboxadd setup command as root to compile the kernel modules.

On some 64-bit guests, you must replace lib with lib64. On older guests that do not run the udev service, you must add the vboxadd service to the default runlevel to ensure that the modules are loaded.

To set up the time synchronization service, add the vboxadd-service service to the default runlevel. To set up the X11 and OpenGL part of the Guest Additions, run the rcvboxadd-x11 setup command. Note that you do not need to enable additional services.

Use the rcvboxadd setup to recompile the guest kernel modules.

If the VM is using VBoxVGA or VBoxSVGA graphics and the vboxvideo driver, reboot the VM to ensure that the new modules are loaded.

If not rebooting, log out and back in to restart the VBoxClient session service with the guest additions.

Linux Guest Screen Resizing

Linux guest screen resizing functionality for guests running VMSVGA graphics configuration uses a standalone daemon called VBoxDRMClient and its Desktop Environment helper counterpart.

VBoxDRMClient runs as a root process and is a bridge between the host and the guest's vmwgfx driver. This means that VBoxDRMClient listens to screen resize hints from the host and forwards them to the vmwgfx driver. This enables guest screen resize functionality to be available before the user has logged in using a GUI.

In order to perform Desktop Environment specific actions, such as setting the primary screen in a multimonitor setup, a Desktop Environment helper is used. Once the user has performed a graphical login operation, the helper daemon starts with user session scope and attempts to connect to VBoxDRMClient using an IPC connection. When VBoxDRMClient has received a corresponding command from the host, it is forwarded to the helper daemon over IPC and the action is then performed.

By default, VBoxDRMClient allows any process to connect to its IPC socket. This can be restricted by using the following steps:

  1. The Guest Additions Linux installer creates a vboxdrmipc user group. A corresponding user needs to be added to this group.

  2. You must set the DRMIpcRestricted guest property, as follows: 

    VBoxManage guestproperty set "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted 1 \
--flags RDONLYGUEST

    It is important to set only the RDONLYGUEST flag for the property, so that it cannot be changed from inside the guest.

Note:

Both steps are required. If one of them is missing, all processes will have access to the IPC socket.

Restricted mode can be disabled by unsetting the guest property, as follows:

VBoxManage guestproperty unset "VM name" /VirtualBox/GuestAdd/DRMIpcRestricted
Updating the Linux Guest Additions

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. There is no need to reboot unless the VM is using VBoxVGA or VBoxSVGA graphics.

Some Linux distributions already come with all or part of the Oracle VirtualBox Guest Additions. You may choose to keep the distribution's version of the Guest Additions but these are often out of date and limited in functionality, so we recommend replacing them with the Guest Additions that come with Oracle VirtualBox.

The Oracle VirtualBox 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. Take a snapshot of the virtual machine before replacing preinstalled Guest Additions.

Uninstalling the Linux Guest Additions

If you have a version of the Guest Additions installed on your virtual machine and want 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 in Installing Guest Additions. Then run the installer for the current Guest Additions with the uninstall parameter from the path that the CD image is mounted on in the guest, as follows: 

sh ./VBoxLinuxAdditions.run uninstall

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.

You can uninstall the Additions as follows:

/opt/VBoxGuestAdditions-version/uninstall.sh

Where /opt/VBoxGuestAdditions-version is the Guest Additions installation directory.

Guest Additions for Oracle Solaris

The Oracle VirtualBox 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.

The Solaris Guest Additions will run on VMs running these versions of Solaris. See also Host and Guest Combinations.

  • Oracle Solaris 11, including Oracle Solaris 11 Express

  • Oracle Solaris 10 4/08 and later

The Guest Additions may work with other distributions that are based on comparable software releases.

Installing the Oracle Solaris Guest Additions

Follow the steps in Installing Guest Additions.

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: 
svcadm restart volfs
Change to the directory where your CD-ROM drive is mounted and run the following command as root: 
pkgadd -G -d ./VBoxSolarisAdditions.pkg

Choose 1 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.

Uninstalling the Oracle Solaris Guest Additions

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:

pkgrm SUNWvboxguest
Updating the Oracle Solaris Guest Additions

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.

Guest Additions for OS/2

Oracle VirtualBox also includes 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. Specifically, seamless windows and automatic guest resizing are not implemented in Guest Additions for OS/2 because of inherent limitations of the OS/2 graphics system.

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 in Installing Guest Additions. The OS/2 Guest Additions are located in the directory \OS2.

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

Shared Folders

With the shared folders feature of Oracle VirtualBox, you can access files of your host system from within one or all virtual machines. 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 can be used with Windows 2000 or later, Linux, and Oracle Solaris guests.

Shared folders physically reside on the host 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.

To share a host folder with a virtual machine in Oracle VirtualBox, you must specify the path of the folder and choose a share name 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.

There are several ways in which shared folders can be set up for a virtual machine:

  • In the window of a running VM, you select Shared Folders from the Devices menu, or click the folder icon on the status bar in the bottom right corner.

  • If a VM is not currently running, you can configure shared folders in the virtual machine's Settings window.

  • From the command line, you can create shared folders using VBoxManage, as follows: 

    VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"

    See VBoxManage sharedfolder.

There are three types of shares:

  • Permanent shares, that are saved with the VM settings.

  • Transient shares, that are added at runtime and disappear when the VM is powered off. These can be created using a check box in Oracle VirtualBox Manager, or by using the --transient option of the VBoxManage sharedfolder add command.

  • Global shared folders are folders shared with all VMs on the host, and stored in VirtualBox settings. Use the Make Global option in Oracle VirtualBox Manager VM Settings, or the global option in VBoxManage sharedfolder.

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 check box in the Oracle VirtualBox Manager, or with the --readonly option of the VBoxManage sharedfolder add command.

Oracle VirtualBox shared folders also support symbolic links, also called symlinks, under the following conditions:

  • The host operating system must support symlinks. For example, a macOS, Linux, or Oracle Solaris host is required.

  • The guest VM must have a version of the Guest Additions installed which supports symlinks. Currently only the Linux and Oracle Solaris Guest Additions support symlinks.

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

    VBoxManage setextradata VM-name VBoxInternal2/SharedFoldersEnableSymlinksCreate/sharename 1

If a symbolic link is created inside a shared folder on the host and the installed Guest Additions do not support symbolic links then the guest will see the target of the symlink as a file inside the shared folder. For example, if a symlink is created to a file on a Linux host:

$ cd /SharedFolder && ln -s filename symlink-to-filename

When the shared folder is viewed on a Windows guest there will be two identical files listed, filename and symlink-to-filename.

Manual Mounting

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

  • 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 My Networking Places, Entire Network, Oracle VirtualBox Shared Folders. By right-clicking on a shared folder and selecting Map Network Drive from the menu that pops up, you can assign a drive letter to that shared folder.

    Alternatively, on the Windows command line, use the following command: 

    net use x: \\vboxsvr\sharename

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

  • In a Linux guest, use the following command: 

    mount -t vboxsf [-o OPTIONS] sharename mountpoint

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

    sharename   mountpoint   vboxsf   defaults  0   0

  • In a Oracle Solaris guest, use the following command: 

    mount -F vboxfs [-o OPTIONS] sharename mountpoint

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

    Here is an example of mounting the shared folder for the user jack on Oracle Solaris: 

    $ 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
$

    Beyond the standard options supplied by the mount command, the following are available: 

    iocharset CHARSET

    This option sets the character set used for I/O operations. Note that on Linux guests, if the iocharset 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. 

    convertcp CHARSET

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

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

  • In an OS/2 guest, use the VBoxControl command to manage shared folders. For example: 

    VBoxControl sharedfolder use D: MyShareName
VBoxControl sharedfolder unuse D:
VBoxControl sharedfolder list

    As with Windows guests, shared folders can also be accessed using UNC , with \\VBoxSF\, \\VBoxSvr\ or \\VBoxSrv\ as the server name and the shared folder name as sharename.

Automatic Mounting

Oracle VirtualBox 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.

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:

  • Windows and OS/2 guests. Search for a free drive letter, starting at Z:. If all drive letters are assigned, the folder is not mounted.

  • Linux and Oracle Solaris guests. Folders are mounted under the /media directory. The folder name is normalized (no spaces, slashes or colons) and is prefixed with sf_.

    For example, if you have a shared folder called myfiles, it will appear as /media/sf_myfiles in the guest.

    The guest properties /VirtualBox/GuestAdd/SharedFolders/MountDir and the more generic /VirtualBox/GuestAdd/SharedFolders/MountPrefix can be used to override the automatic mount directory and prefix. See Guest Properties.

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 vboxsf and the root user.

Clipboard

Oracle VirtualBox enables you to copy text, image and html content from the GUI on the host to the GUI on a VM, and vice versa. You can also copy content between VMs, with other VMs treated as other host applications when configuring the options. For this to work the latest version of the Guest Additions must be installed on the VM.

For security reasons, clipboard access can be configured at runtime on a per-VM basis either using the Shared Clipboard menu item in the Devices menu of the VM or the VBoxManage command.

The following shared clipboard settings are available:

  • Disabled. Disables the copy feature entirely. This is the default when creating a new VM.

  • Host To Guest. Enables copying from the host to the guest only.

  • Guest To Host. Enables copying from the guest to the host only.

  • Bidirectional. Enables copying in both directions: from the host to the guest, and from the guest to the host.

  • Enable Clipboard File Transfers. Allows files (in addition to text, images and html) to be copied to or from the VM.

    • On Linux hosts and guests, Shared Clipboard file transfers are limited to files only, one file per transfer. Transferring symbolic links is not supported.

    • Shared Clipboard file transfers are only tested and supported with the official default file managers of the guest and host operating systems.

To use the VBoxManage command to control the current clipboard mode, see VBoxManage Command Reference. The modifyvm and controlvm commands enable setting of a VM's current clipboard mode from the command line.

Drag and Drop

Oracle VirtualBox enables you to drag and drop content from the host to the guest, and vice versa. For this to work the latest version of the Guest Additions must be installed on the guest.

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.

At the moment drag and drop is implemented for Windows-based and X Window-based systems, both on the host and guest side. As X Window 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 Oracle VirtualBox.

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

Note:

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

When transferring data from the host to the guest OS, the host in this case is the source, whereas the guest OS is the destination. However, when transferring data from the guest OS to the host, the guest OS this time became the source and the host is the destination.

For security reasons drag and drop can be configured at runtime on a per-VM basis either using the Drag and Drop menu item in the Devices menu of the virtual machine, or the VBoxManage command.

On Windows hosts, dragging content between UAC-elevated (User Account Control) programs and non UAC-elevated programs isn't allowed. For example, if you start Oracle VirtualBox with Administrator privileges then dragging to or from Windows Explorer, which runs with regular user privileges by default, is not possible.

The following drag and drop modes are available:

  • Disabled. Disables the drag and drop feature entirely. This is the default when creating a new VM.

  • Host To Guest. Enables drag and drop operations from the host to the guest only.

  • Guest To Host. Enables drag and drop operations from the guest to the host only.

  • Bidirectional. Enables drag and drop operations in both directions: from the host to the guest, and from the guest to the host.

Note:

Drag and drop support depends on the frontend being used. At the moment, only the Oracle VirtualBox Manager frontend provides this functionality.

To use the VBoxManage command to control the current drag and drop mode, see VBoxManage Command Reference. The modifyvm and controlvm commands enable setting of a VM's current drag and drop mode from the command line.

Supported Formats

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

Note:

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.

The following formats are handled by the Oracle VirtualBox drag and drop service:

  • Plain text: From applications such as text editors, internet browsers and terminal windows.

  • Files: From file managers such as Windows Explorer, Nautilus, and Finder.

  • Directories: For directories, the same formats apply as for files.

Hardware-Accelerated Graphics

The Oracle VirtualBox Guest Additions contain hardware 3D support for Windows, Linux, and Oracle Solaris guests. Video decoding acceleration is also used if the host can use it.

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

The 3D acceleration feature is only available for certain Windows, Linux, and Oracle Solaris guests:

  • 3D acceleration with Windows guests requires Windows Vista or later. Vista and Windows 7 guests have Direct3D 9, Windows 8 and newer guests have Direct3D 11.0 or 11.1 depending on the host capabilities. Windows guests also have OpenGL 4.1 support.

  • Linux guests have OpenGL 4.1 support with Mesa3D drivers. 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.

  • OpenGL on Oracle Solaris guests requires X.org server version 1.5 or later.

The video decoding feature is available if the host is x86_64 running Windows or Linux, and the VM is x86_64 running Windows 10 or Windows 11. The VM can use video decoding of all media formats that are supported by the host, and CPU load is reduced during playback of these media formats.

On Linux hosts, you must have one of the following graphics drivers, with Vulkan 1.3 or later, to use video decoding:

  • NVIDIA Linux Graphics Driver
  • Mesa 3D Driver, for AMD and Intel graphics hardware

Video decoding capabilities are disabled by default in Mesa 3D drivers (AMD and Intel), so you must set the following environment variables on the host:

Intel: export ANV_VIDEO_DECODE=1

AMD: export RADV_PERFTEST=video_decode

Seamless Windows

With seamless windows enabled, Oracle VirtualBox enlarges the size of the VM's display to the size of the host desktop, and masks out the guest OS's background, so the windows of the guest appear seamlessly next to the windows of the host.

In Figure 7-1 you can see two calculator applications side by side, one running on the host and the other running on the VM.

Figure 7-1 Seamless Windows on a Host Desktop


Seamless Windows on a Host Desktop

To enable seamless windows, on the virtual machine, press the Host key + L. The Host key is displayed on the taskbar and is normally the right control key.

To disable seamless windows and go back to the normal VM display, press the Host key + L again.

Guest Properties

Oracle VirtualBox enables requests of some properties from a running guest, provided that the Oracle VirtualBox Guest Additions are installed and the VM is running. This provides the following advantages:

  • A number of predefined VM characteristics are automatically maintained by Oracle VirtualBox and can be retrieved on the host. For example, to monitor VM performance and statistics.

  • Arbitrary string data can be exchanged between guest and host. This works in both directions.

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

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

Some of this runtime information is shown when you select Session Information Dialog from a virtual machine's Machine menu.

A more flexible way to use this channel is with the VBoxManage guestproperty command. See VBoxManage guestproperty. For example, to have all the available guest properties for a given running VM listed with their respective values, use this command: 

$ VBoxManage guestproperty enumerate "Windows Vista III"
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: version-number,
    timestamp: 1229098279479515000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: version-numberr40720,
    timestamp: 1229098279651731000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: version-numberr40720,
    timestamp: 1229098279804835000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: version-numberr40720,
    timestamp: 1229098279880611000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: version-numberr40720,
    timestamp: 1229098279882618000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: version-numberr40720,
    timestamp: 1229098279883195000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: version-numberr40720,
    timestamp: 1229098279885027000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: version-numberr40720,
    timestamp: 1229098279886838000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: version-numberr40720,
    timestamp: 1229098279890600000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: version-numberr40720,
    timestamp: 1229098279893056000, flags:
Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: version-numberr40720,
    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:

To query the value of a single property, use the get subcommand as follows: 

$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
Value: Windows Vista Business Edition

To add or change guest properties from the guest, use the tool VBoxControl. This tool is included in the Guest Additions. When started from a Linux guest, this tool requires root privileges for security reasons. 

$ sudo VBoxControl guestproperty enumerate
Oracle VirtualBox Guest Additions Command Line Management Interface Version version-number
Copyright (C) 2005-2025 Oracle and/or its affiliates

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>
      ...

For more complex needs, you can use the Oracle VirtualBox programming interfaces. See Oracle VirtualBox Programming Interfaces.

Using Guest Properties to Wait on VM Events

The properties /VirtualBox/HostInfo/VBoxVer, /VirtualBox/HostInfo/VBoxVerExt or /VirtualBox/HostInfo/VBoxRev can be waited on to detect that the VM state was restored from saved state or snapshot: 

$ VBoxControl guestproperty wait /VirtualBox/HostInfo/VBoxVer

Similarly the /VirtualBox/HostInfo/ResumeCounter can be used to detect that a VM was resumed from the paused state or saved state.

Guest Control File Manager

If you have Guest Additions installed, you can use the Guest Control File Manager to copy files between a virtual machine (VM) and the host system. You can also create new folders, rename files and delete files.

This feature is useful when the VM window of a guest is not visible. For example, when the guest is running in headless mode.

Note:

To use the Guest Control File Manager, the guest must be running. For powered-off guests, it is disabled automatically.

Transferring Files

To use the Guest Control File Manager to transfer files, follow these steps.

  1. Ensure you have the username and password for an account on the guest system, with appropriate permissions on the files you need to access.

  2. Open the Guest Control File Manager. Do either of the following:

    • In the guest VM, select Machine, File Manager.

    • In Oracle VirtualBox Manager, Machines list, click the machine name, and then select File Manager.

    The Host File System pane shows the files on the host system.

  3. In the Guest File System pane, enter the User Name and Password for the user you want to log in as.

    Click Open Session.

    The VM file system appears in the Guest File System pane.

  4. To transfer from the VM to the host, select the file(s) and click Copy From Guest to Host.

    To transfer from the host to the VM, select the file(s) and click Copy From Host to Guest.

  5. Check the progress of the transfer in the Operations pane.

  6. Click Close to end the guest session and the Guest Control File Manager.

Guest Control of Applications

The Guest Additions enable starting of applications inside a guest VM from the host system. This feature can be used to automate deployment of software within the guest.

For this to work, the application needs to be installed on 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.

The Guest Additions for Windows allow for automatic updating. This applies for already installed Guest Additions versions. Also, copying files from host to the guest as well as remotely creating guest directories is available.

To use these features, use the Oracle VirtualBox command line. See VBoxManage guestcontrol.

Memory Overcommitment

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.

Memory Ballooning

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 memory ballooning.

Note:

  • Oracle VirtualBox supports memory ballooning only on 64-bit hosts. It is not supported on macOS hosts.

  • Memory ballooning does not work well with large pages enabled. To turn off large pages support for a VM, run VBoxManage modifyvm vmname --large-pages off

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.

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

The memory made available through the ballooning mechanism is only available for reuse by Oracle VirtualBox. It is not 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.

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

VBoxManage controlvm "VM name" guestmemoryballoon n

where VM name is the name or UUID of the virtual machine in question and n is the amount of memory to allocate from the guest in megabytes. See VBoxManage controlvm.

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: 

VBoxManage modifyvm "VM name" --guest-memory-balloon n

By default, no balloon memory is allocated. This is a VM setting, like other modifyvm settings, and therefore can only be set while the machine is shut down. See VBoxManage modifyvm.

Page Fusion

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.

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. Oracle VirtualBox's Page Fusion technology can efficiently identify these identical memory pages and share them between multiple VMs.

Note:

Oracle VirtualBox supports Page Fusion only on 64-bit hosts, and it is not supported on macOS hosts. Page Fusion currently works only with Windows 2000 and later guests.

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. 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 deduplication. 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 copy on write. All this is fully transparent to the virtual machine.

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

  • Traditional hypervisors scan all 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%.

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

  • 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.

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

VBoxManage modifyvm "VM name" --page-fusion on

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

Note:

Enabling Page Fusion might indirectly increase the chances for malicious guests to successfully attack other VMs running on the same host. See Potentially Insecure Operations.

Controlling Virtual Monitor Topology

X11/XWayland Desktop Environments

The Guest Additions provide services for controlling the guest system's monitor topology. Monitor topology means the resolution of each virtual monitor and its state (disabled/enabled). The resolution of a virtual monitor can be modified on the VM by using the View menu, or from the host side by resizing the window that hosts the virtual monitor, or the VBoxManage controlvm vmname setscreenlayout command. See Specify the Screen Layout for a Display on the Guest VM. Screens enabled must be contiguous or the command will have no effect.

On guest operating systems with X11/XWayland desktops this is put into effect by any of the following services:

VBoxClient --vmsvga
VBoxClient --vmsvga-session
VBoxDRMClient

On X11/XWayland desktops the resizing service is started during desktop session initialization, that is desktop login. On X11 desktops VBoxClient --vmsvga handles screen topology through the RandR extension. On XWayland clients VBoxDRMClient is used. The decision is made automatically at each desktop session start.

On 32-bit guest operating systems VBoxDRMClient is always used, in order to work around bugs.