Table of Contents
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".
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.
Starting with version 4.0, by default, each virtual machine has
one directory on your host computer 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 directory depends on the conventions of the host operating system:
-
On Windows, this is the location returned by the
SHGetFolderPathfunction of the Windows system library Shell32.dll, asking for the user profile. Only on very old Windows versions which don't have this function or where it unexpectedly returns an error, there is a fallback based on environment variables: first%USERPROFILE%is checked, if it doesn't exist then an attempt with%HOMEDRIVE%%HOMEPATH%is made. Typical value isC:\Users\username. -
On Linux, Mac OS X and Solaris, this is generally taken from the environment variable
$HOME, except for the userrootfor which it's taken from the account database (as a workaround for the frequent trouble caused by users using VirtualBox in combination with the toolsudowhich by default doesn't reset the environment variable$HOME). Typical value on Linux and Solaris is/home/usernameand on Mac OS X/Users/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
-
the folder
$HOME/VirtualBox VMs/Example VM/and, in that folder, -
the settings file
Example VM.vboxand -
the virtual disk image
Example VM.vdi.
This is the default layout if you use the "Create new virtual
machine" wizard as described in Section 1.7, “Creating your first virtual machine”. Once
you start working with the VM, additional files will show up: you will
find log files in a subfolder called
Logs, and once you have taken
snapshots, they will appear in a
Snapshots subfolder. For each VM, you
can change the location of its snapshots 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,
use VBoxManage setproperty
machinefolder; see Section 8.30, “VBoxManage setproperty”.
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
.xml file 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/Machines
directory. The default hard disks folder was called "HardDisks" and
resided in the .VirtualBox folder 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.
-
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.
-
Storing virtual disk images, which can grow very large, under the hidden
.VirtualBoxdirectory (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 settings would be irrevocably broken if a user downgraded from 4.0 back to an older version of VirtualBox.
In addition to the files of the virtual machines, VirtualBox
maintains global configuration data. On Linux and Solaris as of VirtualBox 4.3, this
is in the hidden directory $HOME/.config/VirtualBox, although $HOME/.VirtualBox will be used if it exists for compatibility 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 variable, or additionally on Linux or Solaris by using the standard XDG_CONFIG_HOME variable. (Since the global
VirtualBox.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/Machines on 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.
The following table gives a brief overview of the configuration changes between older versions and version 4.0 or above:
Table 10.1. Configuration changes in 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 | Global VirtualBox.xml
file |
Each machine settings file |
| Media registration | Explicit open/close required | Automatic on attach |
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.[46] 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 the VBoxManage command line
tool (see Chapter 8, VBoxManage) and its API (see Chapter 11, VirtualBox programming interfaces).
[46] As an example, before VirtualBox 3.1, it was only possible to enable or disable a single DVD drive in a virtual machine. If it was enabled, then it would always be visible as the secondary master of the IDE controller. With VirtualBox 3.1, DVD drives can be attached to arbitrary slots of arbitrary controllers, so they could be the secondary slave of an IDE controller or in a SATA slot. If you have a machine settings file from an earlier version and upgrade VirtualBox to 3.1 and then move the DVD drive from its default position, this cannot be expressed in the old settings format; the XML machine file would get written in the new format, and a backup file of the old format would be kept.