Sun Microsystems VERSION 3.1.0_BETA2 user manual Advanced topics, VirtualBox configuration data

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. You can globally change some of the lo- cations where VirtualBox keeps extra configuration 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.

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 106) and its API (see chapter 10, VirtualBox programming interfaces, page 154).

The 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

1As 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 an 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.

135