Table of Contents
This chapter provides additional information for readers who are familiar with computer architecture and technology and wish to find out more about how Oracle VM VirtualBox works under the hood. The contents of this chapter are not required reading in order to use Oracle VM VirtualBox successfully.
In Oracle VM VirtualBox, a virtual machine and its settings are described in a virtual machine settings file in XML format. In addition, most virtual machines have one or more virtual hard disks. These are typically represented by disk images, such as those in VDI format. The location of these files may vary, depending on the host operating system. See Section 10.1.1, "The Machine Folder".
Global configuration data for Oracle VM VirtualBox is maintained in another location on the host. See Section 10.1.2, "Global Settings".
By default, each virtual machine has a 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. This is called the machine folder.
By default, this machine folder is located in a common folder called VirtualBox VMs, which Oracle VM 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, as follows:
-
On Windows, this is the location returned by the
SHGetFolderPathfunction of the Windows system library Shell32.dll, asking for the user profile. A typical location isC:\Users\.username -
On Linux, Mac OS X, and Oracle Solaris, this is generally taken from the environment variable
$HOME, except for the userrootwhere it is taken from the account database. This is a workaround for the frequent trouble caused by users using Oracle VM VirtualBox in combination with the tool sudo, which by default does not reset the environment variable$HOME.A typical location on Linux and Oracle Solaris is
/home/and on Mac OS X isusername/Users/.username
For simplicity, we abbreviate the location of the home directory as $HOME. 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", Oracle VM VirtualBox creates the following:
-
A machine folder:
$HOME/VirtualBox VMs/Example VM/ -
In the machine folder, a settings file:
Example VM.vbox -
In the machine folder, a virtual disk image:
Example VM.vdi.
This is the default layout if you use the Create New Virtual Machine wizard described in Section 1.7, "Creating Your First Virtual Machine". Once you start working with the VM, additional files are added. Log files are in a subfolder called Logs, and if you have taken snapshots, they are 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 Oracle VM VirtualBox main window. Then, in the displayed window, click on the General tab. Alternatively, use the VBoxManage setproperty machinefolder command. See Section 8.29, "VBoxManage setproperty".
In addition to the files for the virtual machines, Oracle VM VirtualBox maintains global configuration data in the following directory:
-
Linux and Oracle Solaris:
$HOME/.config/VirtualBox. -
Windows:
$HOME/.VirtualBox. -
Mac OS X:
$HOME/Library/VirtualBox.
Oracle VM VirtualBox creates this configuration directory automatically, if necessary. You can specify an alternate configuration directory by either setting the VBOX_USER_HOME environment variable, or on Linux or Oracle Solaris by using the standard XDG_CONFIG_HOME variable. Since the global VirtualBox.xml settings file points to all other configuration files, this enables switching between several Oracle VM VirtualBox configurations.
In this configuration directory, Oracle VM VirtualBox stores its global settings file, an XML file called VirtualBox.xml. This file includes global configuration options and a list of registered virtual machines with pointers to their XML settings files.
The following table gives a brief overview of the configuration data locations on an Oracle VM VirtualBox host.
Table 10.1. Configuration File Locations
|
Setting |
Location |
|---|---|
|
Default machines folder |
|
|
Default disk image location |
In each machine's folder |
|
Machine settings file extension |
|
|
Media registry |
Each machine settings file Media registration is done automatically when a storage medium is attached to a VM |
Oracle VM VirtualBox uses XML for both the machine settings files and the global configuration file, VirtualBox.xml.
All Oracle VM VirtualBox XML files are versioned. When a new settings file is created, for example because a new virtual machine is created, Oracle VM VirtualBox automatically uses the settings format of the current Oracle VM VirtualBox version. These files may not be readable if you downgrade to an earlier version of Oracle VM VirtualBox. However, when Oracle VM VirtualBox encounters a settings file from an earlier version, such as after upgrading Oracle VM 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 Oracle VM VirtualBox.
In such cases, Oracle VM 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 Oracle VM VirtualBox, then you will need to manually copy these backup files back.
We intentionally do not document the specifications of the Oracle VM 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. Oracle VM 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, Oracle VM VirtualBox Programming Interfaces.