This feature makes the host keyboard lights match those of the virtual machine’s virtual key- board when the machine window is selected. It is currently implemented for Mac OS X and Windows hosts and available as of releases 4.2.24 and 4.3.8. The feature can be enabled using the following command:
VBoxManage setextradata "VM name" GUI/HidLedsSync "1"
In order to disable it, use the same command but change “1” to “0”, or use the VBoxManage command to remove the extra data. This is a per-VM setting and it is disabled by default.
10 Technical background
The contents of this chapter are not required to use VirtualBox successfully. The following is provided as additional information for readers who are more familiar with computer architecture and technology and wish to find out more about how VirtualBox works “under the hood”.
10.1 Where VirtualBox stores its files
In VirtualBox, a virtual machine and its settings are described in a virtual machine settings file in XML format. In addition, most virtual machine have one or more virtual hard disks, which are typically represented by disk images (e.g. in VDI format). Where all these files are stored depends on which version of VirtualBox created the machine.
10.1.1 Machines created by VirtualBox version 4.0 or later
Starting with version 4.0, by default, each virtual machine has one directory on your host com- puter where all the files of that machine are stored – the XML settings file (with a .vbox file extension) and its disk images.
By default, this “machine folder” is placed in a common folder called “VirtualBox VMs”, which VirtualBox creates in the current system user’s home directory. The location of this home direc- tory depends on the conventions of the host operating system:
• On Windows, this is %HOMEDRIVE%%HOMEPATH%; typically something like C:\Documents and Settings\Username\.
• On Mac OS X, this is/Users/username. • On Linux and Solaris, this is/home/username.
For simplicity, we will abbreviate this as $HOME below. Using that convention, the common folder for all virtual machines is$HOME/VirtualBox VMs.
As an example, when you create a virtual machine called “Example VM”, you will find that VirtualBox creates
1. the folder$HOME/VirtualBox VMs/Example VM/and, in that folder, 2. the settings fileExample VM.vboxand
3. the virtual disk imageExample VM.vdi.
This is the default layout if you use the “Create new virtual machine” wizard as described in chapter1.7,Creating your first virtual machine, page18. Once you start working with the VM, additional files will show up: you will find log files in a subfolder calledLogs, and once you have taken snapshots, they will appear in aSnapshotssubfolder. For each VM, you can change the location of its snapsnots folder in the VM settings.
You can change the default machine folder by selecting “Preferences” from the “File” menu in the VirtualBox main window. Then, in the window that pops up, click on the “General” tab. Alternatively, useVBoxManage setproperty machinefolder; see chapter8.27, VBoxManage setproperty, page144.
10.1.2 Machines created by VirtualBox versions before 4.0
If you have upgraded to VirtualBox 4.0 from an earlier version of VirtualBox, you probably have settings files and disks in the earlier file system layout.
Before version 4.0, VirtualBox separated the machine settings files from virtual disk images. The machine settings files had an.xmlfile extension and resided in a folder called “Machines” under the global VirtualBox configuration directory (see the next section). So, for example, on Linux, this was the hidden $HOME/.VirtualBox/Machinesdirectory. The default hard disks folder was called “HardDisks” and resided in the .VirtualBoxfolder as well. Both locations could be changed by the user in the global preferences. (The concept of a “default hard disk folder” has been abandoned with VirtualBox 4.0, since disk images now reside in each machine’s folder by default.)
The old layout had several severe disadvantages.
1. It was very difficult to move a virtual machine from one host to another because the files involved did not reside in the same folder. In addition, the virtual media of all machines were registered with a global registry in the central VirtualBox settings file ($HOME/.VirtualBox/VirtualBox.xml).
To move a machine to another host, it was therefore not enough to move the XML settings file and the disk images (which were in different locations), but the hard disk entries from the global media registry XML had to be meticulously copied as well, which was close to impossible if the machine had snapshots and therefore differencing images.
2. Storing virtual disk images, which can grow very large, under the hidden .VirtualBox directory (at least on Linux and Solaris hosts) made many users wonder where their disk space had gone.
Whereas new VMs created with VirtualBox 4.0 or later will conform to the new layout, for maximum compatibility, old VMs are not converted to the new layout. Otherwise machine set- tings would be irrevocably broken if a user downgraded from 4.0 back to an older version of VirtualBox.
10.1.3 Global configuration data
In addition to the files of the virtual machines, VirtualBox maintains global configura- tion data. On Linux and Solaris as of VirtualBox 4.3, this is in the hidden directory $HOME/.config/VirtualBox, although $HOME/.VirtualBoxwill be used if it exists for com- patibility with earlier versions; on Windows (and on Linux and Solaris with VirtualBox 4.2 and earlier) this is in$HOME/.VirtualBox; on a Mac it resides in$HOME/Library/VirtualBox.
VirtualBox creates this configuration directory automatically if necessary. Optionally, you can supply an alternate configuration directory by setting the VBOX_USER_HOME environment vari- able, or additionally on Linux or Solaris by using the standardXDG_CONFIG_HOMEvariable. (Since the globalVirtualBox.xml settings file points to all other configuration files, this allows for switching between several VirtualBox configurations entirely.)
Most importantly, in this directory, VirtualBox stores its global settings file, another XML file called VirtualBox.xml. This includes global configuration options and the list of registered virtual machines with pointers to their XML settings files. (Neither the location of this file nor its directory has changed with VirtualBox 4.0.)
Before VirtualBox 4.0, all virtual media (disk image files) were also contained in a global registry in this settings file. For compatibility, this media registry still exists if you upgrade VirtualBox and there are media from machines which were created with a version before 4.0. If you have no such machines, then there will be no global media registry; with VirtualBox 4.0, each machine XML file has its own media registry.
Also before VirtualBox 4.0, the default “Machines” folder and the default “HardDisks” folder resided under the VirtualBox configuration directory (e.g. $HOME/.VirtualBox/Machineson
Linux). If you are upgrading from a VirtualBox version before 4.0, files in these directories are not automatically moved in order not to break backwards compatibility.
10.1.4 Summary of 4.0 configuration changes
The following table gives a brief overview of the configuration changes between older versions and version 4.0 or above:
Setting Before 4.0 4.0 or above
Default machines folder $HOME/.VirtualBox/Machines $HOME/VirtualBox VMs
Default disk image location $HOME/.VirtualBox/HardDisks In each machine’s folder Machine settings file
extension
.xml .vbox
Media registry GlobalVirtualBox.xmlfile Each machine settings file
Media registration Explicit open/close required Automatic on attach
10.1.5 VirtualBox XML files
VirtualBox uses XML for both the machine settings files and the global configuration file, VirtualBox.xml.
All VirtualBox XML files are versioned. When a new settings file is created (e.g. because a new virtual machine is created), VirtualBox automatically uses the settings format of the current VirtualBox version. These files may not be readable if you downgrade to an earlier version of VirtualBox. However, when VirtualBox encounters a settings file from an earlier version (e.g. after upgrading VirtualBox), it attempts to preserve the settings format as much as possible. It will only silently upgrade the settings format if the current settings cannot be expressed in the old format, for example because you enabled a feature that was not present in an earlier version of VirtualBox.1 In such cases, VirtualBox backs up the old settings file in the virtual machine’s
configuration directory. If you need to go back to the earlier version of VirtualBox, then you will need to manually copy these backup files back.
We intentionally do not document the specifications of the VirtualBox XML files, as we must reserve the right to modify them in the future. We therefore strongly suggest that you do not edit these files manually. VirtualBox provides complete access to its configuration data through its theVBoxManagecommand line tool (see chapter8,VBoxManage, page113) and its API (see chapter11,VirtualBox programming interfaces, page208).