user_Technical.xml revision 920c195531b0e05b8e18e8d630f99ac92e3c8998
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>The contents of this chapter are not required to use VirtualBox
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning successfully. The following is provided as additional information for
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning readers who are more familiar with computer architecture and technology and
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning wish to find out more about how VirtualBox works "under the hood".</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <title>Where VirtualBox stores its files</title>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>In VirtualBox, a virtual machine and its settings are described in a
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning virtual machine settings file in XML format. In addition, most virtual
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning machine have one or more virtual hard disks, which are typically
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning represented by disk images (e.g. in VDI format). Where all these files are
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning stored depends on which version of VirtualBox created the machine.</para>
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson <title>Machines created by VirtualBox version 4.0 or later</title>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>Starting with version 4.0, by default, each virtual machine has
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning one directory on your host computer where all the files of that machine
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning are stored -- the XML settings file (with a
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>.vbox</computeroutput> file extension) and its disk
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning images.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>By default, this "machine folder" is placed in a common folder
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning called "VirtualBox VMs", which VirtualBox creates in the current system
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning user's home directory. The location of this home directory depends on
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning the conventions of the host operating system:</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <itemizedlist>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>On Windows, this is
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>%HOMEDRIVE%%HOMEPATH%</computeroutput>; typically
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning something like <computeroutput>C:\Documents and
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>On Mac OS X, this is
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>/Users/username</computeroutput>.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>On Linux and Solaris, this is
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>/home/username</computeroutput>.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning </itemizedlist>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>For simplicity, we will abbreviate this as
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>$HOME</computeroutput> below. Using that convention, the
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning common folder for all virtual machines is
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>$HOME/VirtualBox VMs</computeroutput>.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>As an example, when you create a virtual machine called "Example
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning VM", you will find that VirtualBox creates<orderedlist>
081c0aa8fd8d801a6b12e7245814d260095dc103Anders Persson <para>the folder <computeroutput>$HOME/VirtualBox VMs/Example
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning VM/</computeroutput> and, in that folder,</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>the settings file <computeroutput>Example
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>the virtual disk image <computeroutput>Example
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>This is the default layout if you use the "Create new virtual
081c0aa8fd8d801a6b12e7245814d260095dc103Anders Persson machine" wizard as described in <xref linkend="gui-createvm" />. Once
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning you start working with the VM, additional files will show up: you will
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning find log files in a subfolder called
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>Logs</computeroutput>, and once you have taken
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning snapshots, they will appear in a
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>Snapshots</computeroutput> subfolder. For each VM, you
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning can change the location of its snapsnots folder in the VM
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning settings.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>You can change the default machine folder by selecting
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning "Preferences" from the "File" menu in the VirtualBox main window. Then,
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning in the window that pops up, click on the "General" tab. Alternatively,
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning use <computeroutput>VBoxManage setproperty
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <title>Machines created by VirtualBox versions before 4.0</title>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>If you have upgraded to VirtualBox 4.0 from an earlier version of
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning VirtualBox, you probably have settings files and disks in the earlier
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning file system layout.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>Before version 4.0, VirtualBox separated the machine settings
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning files from virtual disk images. The machine settings files had an
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>.xml</computeroutput> file extension and resided in a
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning folder called "Machines" under the global VirtualBox configuration
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning directory (see the next section). So, for example, on Linux, this was
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning the hidden <computeroutput>$HOME/.VirtualBox/Machines</computeroutput>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning directory. The default hard disks folder was called "HardDisks" and
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning resided in the <computeroutput>.VirtualBox</computeroutput> folder as
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning well. Both locations could be changed by the user in the global
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning preferences. (The concept of a "default hard disk folder" has been
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning abandoned with VirtualBox 4.0, since disk images now reside in each
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning machine's folder by default.)</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>The old layout had several severe disadvantages.<orderedlist>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>It was very difficult to move a virtual machine from one
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning host to another because the files involved did not reside in the
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning same folder. In addition, the virtual media of all machines were
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning registered with a global registry in the central VirtualBox
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning settings file
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning (<computeroutput>$HOME/.VirtualBox/VirtualBox.xml</computeroutput>).</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>To move a machine to another host, it was therefore not
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning enough to move the XML settings file and the disk images (which
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning were in different locations), but the hard disk entries from the
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning global media registry XML had to be meticulously copied as well,
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning which was close to impossible if the machine had snapshots and
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning therefore differencing images.</para>
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson <para>Storing virtual disk images, which can grow very large,
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson under the hidden <computeroutput>.VirtualBox</computeroutput>
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson directory (at least on Linux and Solaris hosts) made many users
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson wonder where their disk space had gone.</para>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <para>Whereas new VMs created with VirtualBox 4.0 or later will conform
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed to the new layout, for maximum compatibility, old VMs are
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <emphasis>not</emphasis> converted to the new layout. Otherwise machine
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed settings would be irrevocably broken if a user downgraded from 4.0 back
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed to an older version of VirtualBox.</para>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <para>In addition to the files of the virtual machines, VirtualBox
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed maintains global configuration data. On Linux and Solaris as of VirtualBox 4.3, this
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed is in the hidden directory <computeroutput>$HOME/.config/VirtualBox</computeroutput>, although <computeroutput>$HOME/.VirtualBox</computeroutput> 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 <computeroutput>$HOME/.VirtualBox</computeroutput>; on a Mac it resides in
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <computeroutput>$HOME/Library/VirtualBox</computeroutput>.</para>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <para>VirtualBox creates this configuration directory automatically if
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed necessary. Optionally, you can supply an alternate configuration
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed directory by setting the
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed environment variable, or additionally on Linux or Solaris by using the standard <computeroutput><literal>XDG_CONFIG_HOME</literal></computeroutput> variable. (Since the global
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <computeroutput>VirtualBox.xml</computeroutput> settings file points to
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed all other configuration files, this allows for switching between several
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed VirtualBox configurations entirely.)</para>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <para>Most importantly, in this directory, VirtualBox stores its global
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed settings file, another XML file called
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <computeroutput>VirtualBox.xml</computeroutput>. This includes global
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed configuration options and the list of registered virtual machines with
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed pointers to their XML settings files. (Neither the location of this file
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed nor its directory has changed with VirtualBox 4.0.)</para>
0a0e9771ca0211c15f3ac4466b661c145feeb9e4Darren Reed <para>Before VirtualBox 4.0, all virtual media (disk image files) were
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning also contained in a global registry in this settings file. For
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning compatibility, this media registry still exists if you upgrade
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning VirtualBox and there are media from machines which were created with a
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning version before 4.0. If you have no such machines, then there will be no
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning global media registry; with VirtualBox 4.0, each machine XML file has
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning its own media registry.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>Also before VirtualBox 4.0, the default "Machines" folder and the
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning default "HardDisks" folder resided under the VirtualBox configuration
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> on Linux).
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning If you are upgrading from a VirtualBox version before 4.0, files in
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning these directories are not automatically moved in order not to break
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning backwards compatibility.</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <title>Summary of 4.0 configuration changes</title>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <para>The following table gives a brief overview of the configuration
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning changes between older versions and version 4.0 or above:</para>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <title>Configuration changes in version 4.0 or above</title>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <entry><emphasis role="bold">Setting</emphasis></entry>
3e95bd4ab92abca814bd28e854607d1975c7dc88Anders Persson <entry><emphasis role="bold">Before 4.0</emphasis></entry>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <entry><emphasis role="bold">4.0 or above</emphasis></entry>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <entry><computeroutput>$HOME/.VirtualBox/Machines</computeroutput></entry>
0f1702c5201310f0529cd5abb77652e5e9b241b6Yu Xiangning <entry><computeroutput>$HOME/.VirtualBox/HardDisks</computeroutput></entry>
is created (e.g. because a new virtual machine is created), VirtualBox
file from an earlier version (e.g. after upgrading VirtualBox), it
reflects changes effected through other means, e.g.,
real-mode or protected-mode code (e.g. BIOS code, a DOS guest, or