9 Advanced topics
9.1 VirtualBox configuration data
For each system user, VirtualBox stores configuration data in the user’s home directory,
as per the conventions of the host operating system:
•
On Windows, this is
%HOMEDRIVE%%HOMEPATH%\.VirtualBox
; typically
something like
C:\Documents and Settings\Username\.VirtualBox
.
•
On Mac OS X, this is
$HOME/Library/VirtualBox
.
•
On Unix-like systems (Linux, Solaris), this is
$HOME/.VirtualBox
.
VirtualBox creates this configuration directory automatically, if necessary.
Op-
tionally, you can supply an alternate configuration directory by setting the
VBOX_USER_HOME
environment variable.
VirtualBox stores all its global and machine-specific configuration data in XML doc-
uments. We intentionally do not document the specifications of these 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 configura-
tion data through its the
VBoxManage
command line tool (see chapter
8
,
VBoxManage
reference
, page
100
) and its API (see chapter
10
,
VirtualBox programming interfaces
,
page
143
).
In the configuration directory,
VirtualBox.xml
is the main configuration file.
This includes global configuration options and the media and virtual machine reg-
istry. The media registry links to all CD/DVD, floppy and disk images that have been
added to the Virtual Disk Manager. For each registered VM, there is one entry which
points to the VM configuration file, also in XML format.
You can globally change some of the locations where VirtualBox keeps extra config-
uration and data by selecting “Global settings” from the “File” menu in the VirtualBox
main window. Then, in the window that pops up, click on the “General” tab.
•
Virtual machine settings and files are, by default, saved as XML files in a subdi-
rectory of the
.VirtualBox/Machines
directory. You can change the location
of this main “Machines” folder in the “Global settings” dialog.
By default, for each virtual machine, VirtualBox uses another subdirectory
of the “Machines” directory that carries the same name as the virtual ma-
chine.
As a result, your virtual machine names must conform to the con-
ventions of your operating system for valid file names.
For example, a
127
