diff options
Diffstat (limited to 'doc/manual/en_US/user_Storage.xml')
| -rw-r--r-- | doc/manual/en_US/user_Storage.xml | 2112 |
1 files changed, 2112 insertions, 0 deletions
diff --git a/doc/manual/en_US/user_Storage.xml b/doc/manual/en_US/user_Storage.xml new file mode 100644 index 00000000..ee7053c9 --- /dev/null +++ b/doc/manual/en_US/user_Storage.xml @@ -0,0 +1,2112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Copyright (C) 2006-2022 Oracle and/or its affiliates. + + This file is part of VirtualBox base platform packages, as + available from https://www.virtualbox.org. + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + as published by the Free Software Foundation, in version 3 of the + License. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, see <https://www.gnu.org/licenses>. + + SPDX-License-Identifier: GPL-3.0-only +--> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[ +<!ENTITY % all.entities SYSTEM "all-entities.ent"> +%all.entities; +]> +<chapter id="storage"> + + <title>Virtual Storage</title> + + <para> + As the virtual machine will most probably expect to see a hard disk + built into its virtual computer, &product-name; must be able to + present real storage to the guest as a virtual hard disk. There are + presently three methods by which to achieve this: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; can use large image files on a real hard disk and + present them to a guest as a virtual hard disk. This is the most + common method, described in <xref linkend="vdidetails" />. + </para> + </listitem> + + <listitem> + <para> + iSCSI storage servers can be attached to &product-name;. This is + described in <xref linkend="storage-iscsi" />. + </para> + </listitem> + + <listitem> + <para> + You can allow a virtual machine to access one of your host disks + directly. This is an advanced feature, described in + <xref linkend="rawdisk" />. + </para> + </listitem> + + </itemizedlist> + + <para> + Each such virtual storage device, such as an image file, iSCSI + target, or physical hard disk, needs to be connected to the virtual + hard disk controller that &product-name; presents to a virtual + machine. This is explained in the next section. + </para> + + <sect1 id="harddiskcontrollers"> + + <title>Hard Disk Controllers</title> + + <para> + In a computing device, hard disks and CD/DVD drives are connected + to a device called a hard disk controller, which drives hard disk + operation and data transfers. &product-name; can emulate the most + common types of hard disk controllers typically found in computing + devices: IDE, SATA (AHCI), SCSI, SAS, USB-based, NVMe and + virtio-scsi mass storage devices. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">IDE (ATA)</emphasis> controllers are a + backwards-compatible yet very advanced extension of the disk + controller in the IBM PC/AT (1984). Initially, this interface + worked only with hard disks, but was later extended to also + support CD-ROM drives and other types of removable media. In + physical PCs, this standard uses flat ribbon parallel cables + with 40 or 80 wires. Each such cable can connect two devices, + called device 0 and device 1, to a controller. Typical PCs had + two connectors for such cables. As a result, support for up to + four IDE devices was most common: primary device 0, primary + device 1, secondary device 0, and secondary device 1. + </para> + + <para> + In &product-name;, each virtual machine may have one IDE + controller enabled, which gives you up to four virtual storage + devices that you can attach to the machine. By default, one of + these virtual storage devices, device 0 on the secondary + channel, is preconfigured to be the virtual machine's virtual + CD/DVD drive. However, you can change the default setting. + </para> + + <para> + Even if your guest OS has no support for SCSI or SATA devices, + it should always be able to see an IDE controller. + </para> + + <para> + You can also select which exact type of IDE controller + hardware &product-name; should present to the virtual machine: + PIIX3, PIIX4, or ICH6. This makes no difference in terms of + performance, but if you import a virtual machine from another + virtualization product, the OS in that machine may expect a + particular controller type and crash if it is not found. + </para> + + <para> + After you have created a new virtual machine with the + <emphasis role="bold">New Virtual Machine</emphasis> wizard in + &vbox-mgr;, you will typically see one IDE controller in the + machine's <emphasis role="bold">Storage</emphasis> settings. + The virtual CD/DVD drive will be attached to one of the four + ports of this controller. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial ATA (SATA)</emphasis> is a more + recent standard than IDE. Compared to IDE, it supports both + much higher speeds and more devices per controller. Also, with + physical hardware, devices can be added and removed while the + system is running. The standard interface for SATA controllers + is called Advanced Host Controller Interface (AHCI). + </para> + + <para> + Like a real SATA controller, &product-name;'s virtual SATA + controller operates faster and also consumes fewer CPU + resources than the virtual IDE controller. Also, this enables + you to connect up to 30 virtual hard disks to one machine + instead of just three, when compared to the &product-name; IDE + controller with a DVD drive attached. + </para> + + <para> + For this reason, depending on the selected guest OS, + &product-name; uses SATA as the default for newly created + virtual machines. One virtual SATA controller is created by + default, and the default disk that is created with a new VM is + attached to this controller. + </para> + + <warning> + <para> + The entire SATA controller and the virtual disks attached to + it, including those in IDE compatibility mode, will not be + seen by OSes that do not have device support for AHCI. In + particular, <emphasis>there is no support for AHCI in + Windows versions before Windows Vista</emphasis>. Legacy + Windows versions such as Windows XP, even with SP3 + installed, will not see such disks unless you install + additional drivers. It is possible to switch from IDE to + SATA after installation by installing the SATA drivers and + changing the controller type in the VM + <emphasis role="bold">Settings</emphasis> window. + </para> + + <para> + &product-name; recommends the Intel Matrix Storage drivers, + which can be downloaded from + <ulink url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101" />. + </para> + </warning> + + <para> + To add a SATA controller to a machine for which it has not + been enabled by default, either because it was created by an + earlier version of &product-name;, or because SATA is not + supported by default by the selected guest OS, do the + following. Go to the <emphasis role="bold">Storage</emphasis> + page of the machine's + <emphasis role="bold">Settings</emphasis> window, click + <emphasis role="bold">Add Controller</emphasis> under the + Storage Tree box and then select <emphasis role="bold">Add + SATA Controller</emphasis>. The new controller appears as a + separate PCI device in the virtual machine, and you can add + virtual disks to it. + </para> + + <para> + To change the IDE compatibility mode settings for the SATA + controller, see <xref linkend="vboxmanage-storagectl" />. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">SCSI</emphasis> is another established + industry standard, standing for Small Computer System + Interface. SCSI is as a generic interface for data transfer + between all kinds of devices, including storage devices. SCSI + is still used for connecting some hard disks and tape devices, + but it has mostly been displaced in commodity hardware. It is + still in common use in high-performance workstations and + servers. + </para> + + <para> + Primarily for compatibility with other virtualization + software, &product-name; optionally supports LSI Logic and + BusLogic SCSI controllers, to each of which up to fifteen + virtual hard disks can be attached. + </para> + + <para> + To enable a SCSI controller, on the + <emphasis role="bold">Storage</emphasis> page of a virtual + machine's <emphasis role="bold">Settings</emphasis> window, + click <emphasis role="bold">Add Controller</emphasis> under + the Storage Tree box and then select <emphasis role="bold">Add + SCSI Controller</emphasis>. The new controller appears as a + separate PCI device in the virtual machine. + </para> + + <warning> + <para> + As with the other controller types, a SCSI controller will + only be seen by OSes with device support for it. Windows + 2003 and later ships with drivers for the LSI Logic + controller, while Windows NT 4.0 and Windows 2000 ships with + drivers for the BusLogic controller. Windows XP ships with + drivers for neither. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is + another bus standard which uses the SCSI command set. As + opposed to SCSI physical devices, serial cables are used + instead of parallel cables. This simplifies physical device + connections. In some ways, therefore, SAS is to SCSI what SATA + is to IDE: it enables more reliable and faster connections. + </para> + + <para> + To support high-end guests which require SAS controllers, + &product-name; emulates a LSI Logic SAS controller, which can + be enabled much the same way as a SCSI controller. At this + time, up to 255 devices can be connected to the SAS + controller. + </para> + + <warning> + <para> + As with SATA, the SAS controller will only be seen by OSes + with device support for it. In particular, <emphasis>there + is no support for SAS in Windows before Windows + Vista</emphasis>. So Windows XP, even SP3, will not see such + disks unless you install additional drivers. + </para> + </warning> + </listitem> + + <listitem> + <para> + The <emphasis role="bold">USB mass storage device + class</emphasis> is a standard to connect external storage + devices like hard disks or flash drives to a host through USB. + All major OSes support these devices and ship generic drivers + making third-party drivers superfluous. In particular, legacy + OSes without support for SATA controllers may benefit from USB + mass storage devices. + </para> + + <para> + The virtual USB storage controller offered by &product-name; + works differently to the other storage controller types. While + most storage controllers appear as a single PCI device to the + guest with multiple disks attached to it, the USB-based + storage controller does not appear as virtual storage + controller. Each disk attached to the controller appears as a + dedicated USB device to the guest. + </para> + + <warning> + <para> + Booting from drives attached using USB is only supported + when EFI is used as the BIOS lacks USB support. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Non volatile memory express + (NVMe)</emphasis> is a standard for connecting non volatile + memory (NVM) directly over PCI Express to lift the bandwidth + limitation of the previously used SATA protocol for + solid-state devices. Unlike other standards the command set is + very simple in order to achieve maximum throughput and is not + compatible with ATA or SCSI. OSes need to support NVMe devices + to make use of them. For example, Windows 8.1 added native + NVMe support. For Windows 7, native support was added with an + update. + </para> + + <para> + The NVMe controller is part of the extension pack. + </para> + + <warning> + <para> + Booting from drives attached using NVMe is only supported + when EFI is used as the BIOS lacks the appropriate driver. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Virtual I/O Device SCSI</emphasis> is a + standard to connect virtual storage devices like hard disks or + optical drives to a VM. Recent Linux and Windows versions + support these devices, but Windows needs additional drivers. + Currently virtio-scsi controller support is experimental. + </para> + + <warning> + <para> + The virtio-scsi controller will only be seen by OSes with + device support for it. In particular, <emphasis>there is no + built-in support in Windows</emphasis>. So Windows will not + see such disks unless you install additional drivers. + </para> + </warning> + </listitem> + + </itemizedlist> + + <para> + In summary, &product-name; gives you the following categories of + virtual storage slots: + </para> + + <itemizedlist> + + <listitem> + <para> + Four slots attached to the traditional IDE controller, which + are always present. One of these is typically a virtual CD/DVD + drive. + </para> + </listitem> + + <listitem> + <para> + 30 slots attached to the SATA controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + 15 slots attached to the SCSI controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the SAS controller, if enabled and + supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Eight slots attached to the virtual USB controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 255 slots attached to the NVMe controller, if enabled + and supported by the guest OS. + </para> + </listitem> + + <listitem> + <para> + Up to 256 slots attached to the virtio-scsi controller, if + enabled and supported by the guest OS. + </para> + </listitem> + + </itemizedlist> + + <para> + Given this large choice of storage controllers, you may not know + which one to choose. In general, you should avoid IDE unless it is + the only controller supported by your guest. Whether you use SATA, + SCSI, or SAS does not make any real difference. The variety of + controllers is only supplied by &product-name; for compatibility + with existing hardware and other hypervisors. + </para> + + </sect1> + + <sect1 id="vdidetails"> + + <title>Disk Image Files (VDI, VMDK, VHD, HDD)</title> + + <para> + Disk image files reside on the host system and are seen by the + guest systems as hard disks of a certain geometry. When a guest OS + reads from or writes to a hard disk, &product-name; redirects the + request to the image file. + </para> + + <para> + Like a physical disk, a virtual disk has a size, or capacity, + which must be specified when the image file is created. As opposed + to a physical disk however, &product-name; enables you to expand + an image file after creation, even if it has data already. See + <xref linkend="vboxmanage-modifymedium" />. + </para> + + <para> + &product-name; supports the following types of disk image files: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">VDI.</emphasis> Normally, &product-name; + uses its own container format for guest hard disks. This is + called a Virtual Disk Image (VDI) file. This format is used + when you create a new virtual machine with a new disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VMDK.</emphasis> &product-name; also + fully supports the popular and open VMDK container format that + is used by many other virtualization products, such as VMware. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">VHD.</emphasis> &product-name; also + fully supports the VHD format used by Microsoft. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">HDD.</emphasis> Image files of Parallels + version 2 (HDD format) are also supported. + </para> + + <para> + Due to lack of documentation of the format, newer versions + such as 3 and 4 are not supported. You can however convert + such image files to version 2 format using tools provided by + Parallels. + </para> + </listitem> + + </itemizedlist> + + <para> + Irrespective of the disk capacity and format, as mentioned in + <xref linkend="create-vm-wizard" />, there are two options for + creating a disk image: fixed-size or dynamically allocated. + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Fixed-size.</emphasis> If you create a + fixed-size image, an image file will be created on your host + system which has roughly the same size as the virtual disk's + capacity. So, for a 10 GB disk, you will have a 10 GB file. + Note that the creation of a fixed-size image can take a long + time depending on the size of the image and the write + performance of your hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Dynamically allocated.</emphasis> For + more flexible storage management, use a dynamically allocated + image. This will initially be very small and not occupy any + space for unused virtual disk sectors, but will grow every + time a disk sector is written to for the first time, until the + drive reaches the maximum capacity chosen when the drive was + created. While this format takes less space initially, the + fact that &product-name; needs to expand the image file + consumes additional computing resources, so until the disk + file size has stabilized, write operations may be slower than + with fixed size disks. However, after a time the rate of + growth will slow and the average penalty for write operations + will be negligible. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="virtual-media-manager"> + + <title>The Virtual Media Manager</title> + + <para> + &product-name; keeps track of all the hard disk, CD/DVD-ROM, and + floppy disk images which are in use by virtual machines. These are + often referred to as <emphasis>known media</emphasis> and come + from two sources: + </para> + + <itemizedlist> + + <listitem> + <para> + All media currently attached to virtual machines. + </para> + </listitem> + + <listitem> + <para> + Registered media, for compatibility with legacy &product-name; + versions. + </para> + </listitem> + + </itemizedlist> + + <para> + The known media can be viewed and changed using the + <emphasis role="bold">Virtual Media Manager</emphasis> tool, which + you access by clicking <emphasis role="bold">Media</emphasis> on + the global <emphasis role="bold">Tools</emphasis> menu in + &vbox-mgr;. + </para> + + <figure id="fig-virtual-media-manager"> + <title>The Virtual Media Manager, Showing Hard Disk Images</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + The known media are conveniently grouped in separate tabs for the + supported formats. These formats are: + </para> + + <itemizedlist> + + <listitem> + <para> + Hard disk images, either in &product-name;'s own Virtual Disk + Image (VDI) format, or in the third-party formats listed in + <xref linkend="vdidetails"/>. + </para> + </listitem> + + <listitem> + <para> + CD/DVD images in standard ISO format. + </para> + </listitem> + + <listitem> + <para> + Floppy images in standard RAW format. + </para> + </listitem> + + </itemizedlist> + + <para> + For each image, the Virtual Media Manager shows you the full path + of the image file and other information, such as the virtual + machine the image is currently attached to. + </para> + + <para> + The Virtual Media Manager enables you to do the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Add</emphasis> an image to the known + media. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Create</emphasis> a new disk image. + </para> + + <itemizedlist> + + <listitem> + <para> + For hard disks, the <emphasis role="bold">Create Virtual + Hard Disk</emphasis> wizard is shown. See + <xref linkend="create-virtual-hard-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For optical disks, the <emphasis role="bold">VISO + Creator</emphasis> tool is shown. See + <xref linkend="create-optical-disk-image"/>. + </para> + </listitem> + + <listitem> + <para> + For floppy disks, the <emphasis role="bold">Floppy Disk + Creator</emphasis> tool is shown. See + <xref linkend="create-floppy-disk-image"/>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Copy</emphasis> an image to create + another one. + </para> + + <para> + For virtual hard disks, you can specify one of the following + target types: VDI, VHD, or VMDK. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Move</emphasis> an image to another + location. + </para> + + <para> + A file dialog prompts you for the new image file location. + </para> + + <para> + When you use the Virtual Media Manager to move a disk image, + &product-name; updates all related configuration files + automatically. + </para> + + <note> + <para> + Always use the Virtual Media Manager or the + <command>VBoxManage modifymedium</command> command to move a + disk image. + </para> + + <para> + If you use a file management feature of the host OS to move + a disk image to a new location, run the <command>VBoxManage + modifymedium</command> <option>--setlocation</option> + command to configure the new path of the disk image on the + host file system. This command updates the &product-name; + configuration automatically. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Remove</emphasis> an image from the + known media. You can optionally delete the image file when + removing the image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Release</emphasis> an image to detach it + from a VM. This action only applies if the image is currently + attached to a VM as a virtual hard disk. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Clear</emphasis> all inaccessible disk + images from the list. The disk images are released from the + VMs they are attached to and removed from the known media. + </para> + + <note> + <para> + This option is for optical disks and floppy disks only. + </para> + </note> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Search</emphasis> for an image by name + or UUID. + </para> + </listitem> + + <listitem> + <para> + View and edit the <emphasis role="bold">Properties</emphasis> + of a disk image. + </para> + + <para> + Available properties include the following: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Type:</emphasis> Specifies the + snapshot behavior of the disk. See + <xref linkend="hdimagewrites"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Location:</emphasis> Specifies the + location of the disk image file on the host system. You + can use a file dialog to browse for the disk image + location. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Description:</emphasis> Specifies a + short description of the disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Specifies the size + of the disk image. You can use the slider to increase or + decrease the disk image size. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Information:</emphasis> Specifies + detailed information about the disk image. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Refresh</emphasis> the property values + of the selected disk image. + </para> + </listitem> + + </itemizedlist> + + <para> + To perform these actions, highlight the medium in the Virtual + Media Manager and then do one of the following: + </para> + + <itemizedlist> + + <listitem> + <para> + Click an icon in the Virtual Media Manager toolbar. + </para> + </listitem> + + <listitem> + <para> + Right-click the medium and select an option. + </para> + </listitem> + + </itemizedlist> + + <para> + Use the <emphasis role="bold">Storage</emphasis> page in a VM's + <emphasis role="bold">Settings</emphasis> window to create a new + disk image. By default, disk images are stored in the VM's folder. + </para> + + <para> + You can copy hard disk image files to other host systems and then + import them in to VMs from the host system. However, some Windows + guest OSes may require that you configure the new VM in a similar + way to the old one. + </para> + + <note> + <para> + Do not simply make copies of virtual disk images. If you import + such a second copy into a VM, &product-name; issues an error + because &product-name; assigns a universally unique identifier + (UUID) to each disk image to ensure that it is only used one + time. See <xref linkend="cloningvdis" />. Also, if you want to + copy a VM to another system, use the &product-name; import and + export features. See <xref linkend="ovf" />. + </para> + </note> + + <sect2 id="create-virtual-hard-disk-image"> + + <title>Creating a Virtual Hard Disk Image</title> + + <para> + Use the <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard to create a hard disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Hard Disks</emphasis> tab + in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Create Virtual Hard + Disk</emphasis> wizard is shown. + </para> + + <figure id="fig-virtual-hard-disk-wizard"> + <title>Create Virtual Hard Disk Wizard</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-hard-disk-wizard.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Virtual Hard Disk File + Type</emphasis> page, select a file type for the new virtual + hard disk image. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">Storage on Physical Hard + Disk</emphasis> page, select whether the size of the virtual + hard disk file is dynamically allocated or is of fixed size. + </para> + + <para> + Click <emphasis role="bold">Next</emphasis>. + </para> + </listitem> + + <listitem> + <para> + On the <emphasis role="bold">File Location and + Size</emphasis> page, configure the location of the virtual + hard disk file and use the slider to set the size limit for + the virtual hard disk. + </para> + + <para> + Click <emphasis role="bold">Finish</emphasis> to create the + virtual hard disk file. + </para> + + <para> + The virtual hard disk image is created in the specified + location and added to the <emphasis role="bold">Hard + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-optical-disk-image"> + + <title>Creating a Virtual Optical Disk Image</title> + + <para> + Use the <emphasis role="bold">VISO Creator</emphasis> tool to + create a virtual optical disk image. This enables you to create + a virtual ISO from selected files on the host. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Optical Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">VISO Creator</emphasis> tool is + shown. + </para> + </listitem> + + <listitem> + <para> + Create the virtual ISO file. + </para> + + <orderedlist> + + <listitem> + <para> + Configure the name of the ISO file. + </para> + + <para> + Click <emphasis role="bold">Configuration</emphasis> and + enter a name in the <emphasis role="bold">Viso + Name</emphasis> field. + </para> + </listitem> + + <listitem> + <para> + Add files to your virtual ISO. + </para> + + <para> + In the <emphasis role="bold">Host File System</emphasis> + pane, select files to copy from the host system to the + virtual ISO. + </para> + + <para> + Click <emphasis role="bold">Add Items To + VISO</emphasis>. The files are displayed in the + <emphasis role="bold">VISO Content</emphasis> pane. + </para> + + <para> + The following file operations are also available: + </para> + + <itemizedlist> + + <listitem> + <para> + To create folders on the virtual ISO, click + <emphasis role="bold">Create New + Directory</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove files from the virtual ISO, select files + in the <emphasis role="bold">VISO Content</emphasis> + pane and click <emphasis role="bold">Remove Items + From VISO</emphasis>. + </para> + </listitem> + + <listitem> + <para> + To remove <emphasis>all</emphasis> files from the + virtual ISO, click <emphasis role="bold">Reset the + VISO Content</emphasis>. + </para> + </listitem> + + </itemizedlist> + </listitem> + + </orderedlist> + </listitem> + + <listitem> + <para> + Create the virtual ISO image. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + A virtual ISO file with the specified name and content is + created. + </para> + </listitem> + + </orderedlist> + + </sect2> + + <sect2 id="create-floppy-disk-image"> + + <title>Creating a Virtual Floppy Disk Image</title> + + <para> + Use the <emphasis role="bold">Floppy Disk Creator</emphasis> + tool to create a floppy disk image. + </para> + + <orderedlist> + + <listitem> + <para> + Display the <emphasis role="bold">Floppy Disks</emphasis> + tab in Virtual Media Manager and click + <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The <emphasis role="bold">Floppy Disk Creator</emphasis> + tool is shown. + </para> + </listitem> + + <listitem> + <para> + Configure the following settings: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">File Path:</emphasis> The name and + location of the floppy disk image. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Size:</emphasis> Select from the + list of supported floppy disk sizes. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Format Disk as FAT 12:</emphasis> + This is the default format used for most floppy disks. + For an unformatted disk, do not select this option. + </para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para> + Create the floppy disk image file. + </para> + + <para> + Click <emphasis role="bold">Create</emphasis>. + </para> + + <para> + The floppy disk image is created in the specified location + and added to the <emphasis role="bold">Floppy + Disks</emphasis> tab in Virtual Media Manager. + </para> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + + <sect1 id="hdimagewrites"> + + <title>Special Image Write Modes</title> + + <para> + For each virtual disk image supported by &product-name;, you can + determine separately how it should be affected by write operations + from a virtual machine and snapshot operations. This applies to + all of the aforementioned image formats (VDI, VMDK, VHD, or HDD) + and irrespective of whether an image is fixed-size or dynamically + allocated. + </para> + + <para> + By default, images are in <emphasis>normal</emphasis> mode. To + mark an existing image with one of the non-standard modes listed + below, use <command>VBoxManage modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium" />. Alternatively, use + <command>VBoxManage storageattach</command> to attach the image to + a VM and specify the <option>--mtype</option> argument. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + The available virtual disk image modes are as follows: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Normal images</emphasis> have no + restrictions on how guests can read from and write to the + disk. This is the default image mode. + </para> + + <para> + When you take a snapshot of your virtual machine as described + in <xref linkend="snapshots" />, the state of a normal hard + disk is recorded together with the snapshot, and when + reverting to the snapshot, its state will be fully reset. + </para> + + <para> + The image file itself is not reset. Instead, when a snapshot + is taken, &product-name; <emphasis>freezes</emphasis> the + image file and no longer writes to it. For the write + operations from the VM, a second, + <emphasis>differencing</emphasis> image file is created which + receives only the changes to the original image. See + <xref linkend="diffimages"/>. + </para> + + <para> + While you can attach the same normal image to more than one + virtual machine, only one of these virtual machines attached + to the same image file can be executed simultaneously, as + otherwise there would be conflicts if several machines write + to the same image file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Write-through hard disks</emphasis> are + completely unaffected by snapshots. Their state is + <emphasis>not</emphasis> saved when a snapshot is taken, and + not restored when a snapshot is restored. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Shareable hard disks</emphasis> are a + variant of write-through hard disks. In principle they behave + exactly the same. Their state is <emphasis>not</emphasis> + saved when a snapshot is taken, and not restored when a + snapshot is restored. The difference only shows if you attach + such disks to several VMs. Shareable disks may be attached to + several VMs which may run concurrently. This makes them + suitable for use by cluster filesystems between VMs and + similar applications which are explicitly prepared to access a + disk concurrently. Only fixed size images can be used in this + way, and dynamically allocated images are rejected. + </para> + + <warning> + <para> + This is an expert feature, and misuse can lead to data loss, + as regular filesystems are not prepared to handle + simultaneous changes by several parties. + </para> + </warning> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Immutable images</emphasis> only + remember write accesses temporarily while the virtual machine + is running. All changes are lost when the virtual machine is + powered on the next time. As a result, as opposed to Normal + images, the same immutable image can be used with several + virtual machines without restrictions. + </para> + + <para> + Creating an immutable image makes little sense since it would + be initially empty and lose its contents with every machine + restart. You would have a disk that is always unformatted when + the machine starts up. Instead, you can first create a normal + image and then later mark it as immutable when you decide that + the contents are useful. + </para> + + <para> + If you take a snapshot of a machine with immutable images, + then on every machine power-up, those images are reset to the + state of the last (current) snapshot, instead of the state of + the original immutable image. + </para> + + <note> + <para> + As a special exception, immutable images are + <emphasis>not</emphasis> reset if they are attached to a + machine in a saved state or whose last snapshot was taken + while the machine was running. This is called an + <emphasis>online snapshot</emphasis>. As a result, if the + machine's current snapshot is an online snapshot, its + immutable images behave exactly like the a normal image. To + reenable the automatic resetting of such images, delete the + current snapshot of the machine. + </para> + </note> + + <para> + &product-name; never writes to an immutable image directly at + all. All write operations from the machine are directed to a + differencing image. The next time the VM is powered on, the + differencing image is reset so that every time the VM starts, + its immutable images have exactly the same content. + </para> + + <para> + The differencing image is only reset when the machine is + powered on from within &product-name;, not when you reboot by + requesting a reboot from within the machine. This is also why + immutable images behave as described above when snapshots are + also present, which use differencing images as well. + </para> + + <para> + If the automatic discarding of the differencing image on VM + startup does not fit your needs, you can turn it off using the + <option>autoreset</option> parameter of <command>VBoxManage + modifymedium</command>. See + <xref linkend="vboxmanage-modifymedium"/>. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Multiattach mode images</emphasis> can + be attached to more than one virtual machine at the same time, + even if these machines are running simultaneously. For each + virtual machine to which such an image is attached, a + differencing image is created. As a result, data that is + written to such a virtual disk by one machine is not seen by + the other machines to which the image is attached. Each + machine creates its own write history of the multiattach + image. + </para> + + <para> + Technically, a multiattach image behaves identically to an + immutable image except the differencing image is not reset + every time the machine starts. + </para> + + <para> + This mode is useful for sharing files which are almost never + written, for instance picture galleries, where every guest + changes only a small amount of data and the majority of the + disk content remains unchanged. The modified blocks are stored + in differencing images which remain relatively small and the + shared content is stored only once at the host. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Read-only images</emphasis> are used + automatically for CD/DVD images, since CDs/DVDs can never be + written to. + </para> + </listitem> + + </itemizedlist> + + <para> + The following scenario illustrates the differences between the + various image modes, with respect to snapshots. + </para> + + <para> + Assume you have installed your guest OS in your VM, and you have + taken a snapshot. Later, your VM is infected with a virus and you + would like to go back to the snapshot. With a normal hard disk + image, you simply restore the snapshot, and the earlier state of + your hard disk image will be restored as well and your virus + infection will be undone. With an immutable hard disk, all it + takes is to shut down and power on your VM, and the virus + infection will be discarded. With a write-through image however, + you cannot easily undo the virus infection by means of + virtualization, but will have to disinfect your virtual machine + like a real computer. + </para> + + <para> + You might find write-through images useful if you want to preserve + critical data irrespective of snapshots. As you can attach more + than one image to a VM, you may want to have one immutable image + for the OS and one write-through image for your data files. + </para> + + </sect1> + + <sect1 id="diffimages"> + + <title>Differencing Images</title> + + <para> + The previous section mentioned differencing images and how they + are used with snapshots, immutable images, and multiple disk + attachments. This section describes in more detail how + differencing images work. + </para> + + <para> + A differencing image is a special disk image that only holds the + differences to another image. A differencing image by itself is + useless, it must always refer to another image. The differencing + image is then typically referred to as a + <emphasis>child</emphasis>, which holds the differences to its + <emphasis>parent</emphasis>. + </para> + + <para> + When a differencing image is active, it receives all write + operations from the virtual machine instead of its parent. The + differencing image only contains the sectors of the virtual hard + disk that have changed since the differencing image was created. + When the machine reads a sector from such a virtual hard disk, it + looks into the differencing image first. If the sector is present, + it is returned from there. If not, &product-name; looks into the + parent. In other words, the parent becomes + <emphasis>read-only</emphasis>. It is never written to again, but + it is read from if a sector has not changed. + </para> + + <para> + Differencing images can be chained. If another differencing image + is created for a virtual disk that already has a differencing + image, then it becomes a <emphasis>grandchild</emphasis> of the + original parent. The first differencing image then becomes + read-only as well, and write operations only go to the + second-level differencing image. When reading from the virtual + disk, &product-name; needs to look into the second differencing + image first, then into the first if the sector was not found, and + then into the original image. + </para> + + <para> + There can be an unlimited number of differencing images, and each + image can have more than one child. As a result, the differencing + images can form a complex tree with parents, siblings, and + children, depending on how complex your machine configuration is. + Write operations always go to the one <emphasis>active</emphasis> + differencing image that is attached to the machine, and for read + operations, &product-name; may need to look up all the parents in + the chain until the sector in question is found. You can view such + a tree in the Virtual Media Manager. + </para> + + <figure id="fig-diff-images"> + <title>Differencing Images, Shown in Virtual Media Manager</title> + <mediaobject> + <imageobject> + <imagedata align="center" fileref="images/virtual-disk-manager-2.png" + width="12cm" /> + </imageobject> + </mediaobject> + </figure> + + <para> + In all of these situations, from the point of view of the virtual + machine, the virtual hard disk behaves like any other disk. While + the virtual machine is running, there is a slight run-time I/O + overhead because &product-name; might need to look up sectors + several times. This is not noticeable however since the tables + with sector information are always kept in memory and can be + looked up quickly. + </para> + + <para> + Differencing images are used in the following situations: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Snapshots.</emphasis> When you create a + snapshot, as explained in the previous section, &product-name; + <emphasis>freezes</emphasis> the images attached to the + virtual machine and creates differencing images for each image + that is not in <emphasis>write-through</emphasis> mode. From + the point of view of the virtual machine, the virtual disks + continue to operate before, but all write operations go into + the differencing images. Each time you create another + snapshot, for each hard disk attachment, another differencing + image is created and attached, forming a chain or tree. + </para> + + <para> + In the above screenshot, you see that the original disk image + is now attached to a snapshot, representing the state of the + disk when the snapshot was taken. + </para> + + <para> + If you <emphasis>restore</emphasis> a snapshot, and want to go + back to the exact machine state that was stored in the + snapshot, the following happens: + </para> + + <itemizedlist> + + <listitem> + <para> + &product-name; copies the virtual machine settings that + were copied into the snapshot back to the virtual machine. + As a result, if you have made changes to the machine + configuration since taking the snapshot, they are undone. + </para> + </listitem> + + <listitem> + <para> + If the snapshot was taken while the machine was running, + it contains a saved machine state, and that state is + restored as well. After restoring the snapshot, the + machine will then be in Saved state and resume execution + from there when it is next started. Otherwise the machine + will be in Powered Off state and do a full boot. + </para> + </listitem> + + <listitem> + <para> + For each disk image attached to the machine, the + differencing image holding all the write operations since + the current snapshot was taken is thrown away, and the + original parent image is made active again. If you + restored the root snapshot, then this will be the root + disk image for each attachment. Otherwise, some other + differencing image descended from it. This effectively + restores the old machine state. + </para> + </listitem> + + </itemizedlist> + + <para> + If you later <emphasis>delete</emphasis> a snapshot in order + to free disk space, for each disk attachment, one of the + differencing images becomes obsolete. In this case, the + differencing image of the disk attachment cannot simply be + deleted. Instead, &product-name; needs to look at each sector + of the differencing image and needs to copy it back into its + parent. This is called "merging" images and can be a + potentially lengthy process, depending on how large the + differencing image is. It can also temporarily need a + considerable amount of extra disk space, before the + differencing image obsoleted by the merge operation is + deleted. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Immutable images.</emphasis> When an + image is switched to immutable mode, a differencing image is + created as well. As with snapshots, the parent image then + becomes read-only, and the differencing image receives all the + write operations. Every time the virtual machine is started, + all the immutable images which are attached to it have their + respective differencing image thrown away, effectively + resetting the virtual machine's virtual disk with every + restart. + </para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="cloningvdis"> + + <title>Cloning Disk Images</title> + + <para> + You can duplicate hard disk image files on the same host to + quickly produce a second virtual machine with the same OS setup. + However, you should <emphasis>only</emphasis> make copies of + virtual disk images using the utility supplied with + &product-name;. See <xref linkend="vboxmanage-clonemedium" />. + This is because &product-name; assigns a UUID to each disk image, + which is also stored inside the image, and &product-name; will + refuse to work with two images that use the same number. If you do + accidentally try to reimport a disk image which you copied + normally, you can make a second copy using the <command>VBoxManage + clonevm</command> command and import that instead. + </para> + + <para> + Note that Linux distributions identify the boot hard disk from the + ID of the drive. The ID &product-name; reports for a drive is + determined from the UUID of the virtual disk image. So if you + clone a disk image and try to boot the copied image the guest + might not be able to determine its own boot disk as the UUID + changed. In this case you have to adapt the disk ID in your boot + loader script, for example + <filename>/boot/grub/menu.lst</filename>. The disk ID looks like + the following: + </para> + +<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen> + + <para> + The ID for the copied image can be determined as follows: + </para> + +<screen>hdparm -i /dev/sda</screen> + + </sect1> + + <sect1 id="iocaching"> + + <title>Host Input/Output Caching</title> + + <para> + &product-name; can optionally disable the I/O caching that the + host OS would otherwise perform on disk image files. + </para> + + <para> + Traditionally, &product-name; has opened disk image files as + normal files, which results in them being cached by the host OS + like any other file. The main advantage of this is speed: when the + guest OS writes to disk and the host OS cache uses delayed + writing, the write operation can be reported as completed to the + guest OS quickly while the host OS can perform the operation + asynchronously. Also, when you start a VM a second time and have + enough memory available for the OS to use for caching, large parts + of the virtual disk may be in system memory, and the VM can access + the data much faster. + </para> + + <para> + Note that this applies only to image files. Buffering does not + occur for virtual disks residing on remote iSCSI storage, which is + the more common scenario in enterprise-class setups. See + <xref linkend="storage-iscsi" />. + </para> + + <para> + While buffering is a useful default setting for virtualizing a few + machines on a desktop computer, there are some disadvantages to + this approach: + </para> + + <itemizedlist> + + <listitem> + <para> + Delayed writing through the host OS cache is less secure. When + the guest OS writes data, it considers the data written even + though it has not yet arrived on a physical disk. If for some + reason the write does not happen, such as power failure or + host crash, the likelihood of data loss increases. + </para> + </listitem> + + <listitem> + <para> + Disk image files tend to be very large. Caching them can + therefore quickly use up the entire host OS cache. Depending + on the efficiency of the host OS caching, this may slow down + the host immensely, especially if several VMs run at the same + time. For example, on Linux hosts, host caching may result in + Linux delaying all writes until the host cache is nearly full + and then writing out all these changes at once, possibly + stalling VM execution for minutes. This can result in I/O + errors in the guest as I/O requests time out there. + </para> + </listitem> + + <listitem> + <para> + Physical memory is often wasted as guest OSes typically have + their own I/O caches, which may result in the data being + cached twice, in both the guest and the host caches, for + little effect. + </para> + </listitem> + + </itemizedlist> + + <para> + If you decide to disable host I/O caching for the above reasons, + &product-name; uses its own small cache to buffer writes, but no + read caching since this is typically already performed by the + guest OS. In addition, &product-name; fully supports asynchronous + I/O for its virtual SATA, SCSI, and SAS controllers through + multiple I/O threads. + </para> + + <para> + Since asynchronous I/O is not supported by IDE controllers, for + performance reasons, you may want to leave host caching enabled + for your VM's virtual IDE controllers. + </para> + + <para> + For this reason, &product-name; enables you to configure whether + the host I/O cache is used for each I/O controller separately. + Either select the <emphasis role="bold">Use Host I/O + Cache</emphasis> check box in the + <emphasis role="bold">Storage</emphasis> settings for a given + virtual storage controller, or use the following + <command>VBoxManage</command> command to disable the host I/O + cache for a virtual storage controller: + </para> + +<screen>VBoxManage storagectl "VM name" --name <controllername> --hostiocache off</screen> + + <para> + See <xref linkend="vboxmanage-storagectl" />. + </para> + + <para> + For the above reasons, &product-name; uses SATA controllers by + default for new virtual machines. + </para> + + </sect1> + + <sect1 id="storage-bandwidth-limit"> + + <title>Limiting Bandwidth for Disk Images</title> + + <para> + &product-name; supports limiting of the maximum bandwidth used for + asynchronous I/O. Additionally it supports sharing limits through + bandwidth groups for several images. It is possible to have more + than one such limit. + </para> + + <para> + Limits are configured using <command>VBoxManage</command>. The + example below creates a bandwidth group named Limit, sets the + limit to 20 MB per second, and assigns the group to the attached + disks of the VM: + </para> + +<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M +VBoxManage storageattach "VM name" --storagectl "SATA" --port 0 --device 0 --type hdd + --medium disk1.vdi --bandwidthgroup Limit +VBoxManage storageattach "VM name" --storagectl "SATA" --port 1 --device 0 --type hdd + --medium disk2.vdi --bandwidthgroup Limit</screen> + + <para> + All disks in a group share the bandwidth limit, meaning that in + the example above the bandwidth of both images combined can never + exceed 20 MBps. However, if one disk does not require bandwidth + the other can use the remaining bandwidth of its group. + </para> + + <para> + The limits for each group can be changed while the VM is running, + with changes being picked up immediately. The example below + changes the limit for the group created in the example above to 10 + MBps: + </para> + +<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen> + + </sect1> + + <sect1 id="storage-cds"> + + <title>CD/DVD Support</title> + + <para> + Virtual CD/DVD drives by default support only reading. The medium + configuration is changeable at runtime. You can select between the + following options to provide the medium data: + </para> + + <itemizedlist> + + <listitem> + <para> + <emphasis role="bold">Host Drive</emphasis> defines that the + guest can read from the medium in the host drive. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Image file</emphasis> gives the guest + read-only access to the data in the image. This is typically + an ISO file. + </para> + </listitem> + + <listitem> + <para> + <emphasis role="bold">Empty</emphasis> means a drive without + an inserted medium. + </para> + </listitem> + + </itemizedlist> + + <para> + Changing between the above, or changing a medium in the host drive + that is accessed by a machine, or changing an image file will + signal a medium change to the guest OS. The guest OS can then + react to the change, for example by starting an installation + program. + </para> + + <para> + Medium changes can be prevented by the guest, and &product-name; + reflects that by locking the host drive if appropriate. You can + force a medium removal in such situations by using the VirtualBox + Manager or the <command>VBoxManage</command> command line tool. + Effectively this is the equivalent of the emergency eject which + many CD/DVD drives provide, with all associated side effects. The + guest OS can issue error messages, just like on real hardware, and + guest applications may misbehave. Use this with caution. + </para> + + <note> + <para> + The identification string of the drive provided to the guest, + displayed by configuration tools such as the Windows Device + Manager, is always VBOX CD-ROM, irrespective of the current + configuration of the virtual drive. This is to prevent hardware + detection from being triggered in the guest OS every time the + configuration is changed. + </para> + </note> + + <para> + The standard CD/DVD emulation enables reading of standard data CD + and DVD formats only. As an experimental feature, for additional + capabilities, it is possible to give the guest direct access to + the CD/DVD host drive by enabling <emphasis>passthrough</emphasis> + mode. Depending on the host hardware, this may potentially enable + the following things to work: + </para> + + <itemizedlist> + + <listitem> + <para> + CD/DVD writing from within the guest, if the host DVD drive is + a CD/DVD writer + </para> + </listitem> + + <listitem> + <para> + Playing audio CDs + </para> + </listitem> + + <listitem> + <para> + Playing encrypted DVDs + </para> + </listitem> + + </itemizedlist> + + <para> + To enable host drive passthrough you can use the + <option>--passthrough</option> option of the <command>VBoxManage + storageattach</command> command. See + <xref linkend="vboxmanage-storageattach" />. + </para> + + <para> + Even if passthrough is enabled, unsafe commands, such as updating + the drive firmware, will be blocked. Video CD formats are never + supported, not even in passthrough mode, and cannot be played from + a virtual machine. + </para> + + <para> + On Oracle Solaris hosts, passthrough requires running + &product-name; with real root permissions due to security measures + enforced by the host. + </para> + + </sect1> + + <sect1 id="storage-iscsi"> + + <title>iSCSI Servers</title> + + <para> + iSCSI stands for <emphasis>Internet SCSI</emphasis> and is a + standard that supports use of the SCSI protocol over Internet + (TCP/IP) connections. Especially with the advent of Gigabit + Ethernet, it has become affordable to attach iSCSI storage servers + simply as remote hard disks to a computer network. In iSCSI + terminology, the server providing storage resources is called an + <emphasis>iSCSI target</emphasis>, while the client connecting to + the server and accessing its resources is called an + <emphasis>iSCSI initiator</emphasis>. + </para> + + <para> + &product-name; can transparently present iSCSI remote storage to a + virtual machine as a virtual hard disk. The guest OS will not see + any difference between a virtual disk image (VDI file) and an + iSCSI target. To achieve this, &product-name; has an integrated + iSCSI initiator. + </para> + + <para> + &product-name;'s iSCSI support has been developed according to the + iSCSI standard and should work with all standard-conforming iSCSI + targets. To use an iSCSI target with &product-name;, you must use + the command line. See <xref linkend="vboxmanage-storageattach" />. + </para> + + </sect1> + + <sect1 id="vboximg-mount"> + + <title>vboximg-mount: A Utility for FUSE Mounting a Virtual Disk Image</title> + + <para> + <command>vboximg-mount</command> is a command line utility for Mac + OS and Linux hosts that provides raw access to an &product-name; + virtual disk image on the host system. Use this utility to mount, + view, and optionally modify the disk image contents. + </para> + + <para> + The utility is based on Filesystem in Userspace (FUSE) technology + and uses the VirtualBox runtime engine. Ensure that &product-name; + is running on the host system. + </para> + + <note> + <para> + When using <command>vboximg-mount</command>, ensure that the + following conditions apply: + </para> + + <itemizedlist> + + <listitem> + <para> + The disk image is not being used by any other systems, such + as by guest VMs. + </para> + </listitem> + + <listitem> + <para> + No VMs are running on the host system. + </para> + </listitem> + + </itemizedlist> + </note> + + <para> + Raw access using FUSE is preferred over direct loopback mounting + of virtual disk images, because it is snapshot aware. It can + selectively merge disk differencing images in an exposed virtual + hard disk, providing historical or up-to-date representations of + the virtual disk contents. + </para> + + <para> + <command>vboximg-mount</command> enables you to view information + about registered VMs, their attached disk media, and any + snapshots. Also, you can view partition information for a disk + image. + </para> + + <para> + The <command>vboximg-mount </command>command includes experimental + read-only access to file systems inside a VM disk image. This + feature enables you to extract some files from the disk image + without starting the VM and without requiring third-party file + system drivers on the host system. FAT, NTFS, ext2, ext3, and ext4 + file systems are supported. + </para> + + <para> + Use the <option>--help</option> option to view information about + the <command>vboximg-mount</command> command usage. The complete + command reference is described in + <xref linkend="man_vboximg-mount" />. + </para> + + <para> + When <command>vboximg-mount</command> mounts an &product-name; + disk image, it creates a one level deep file system at a mount + point that you specify. The file system includes a device node + that represents the synthesized disk image as a readable or + readable-writeable bytestream. This bytestream can be mounted + either by using the host OS or by using other FUSE-based file + systems. + </para> + + <sect2 id="vboximg-mount-display"> + + <title>Viewing Detailed Information About a Virtual Disk Image</title> + + <para> + The following examples show how to use the + <command>vboximg-mount</command> command to view information + about virtual disk images. + </para> + + <para> + The following command outputs detailed information about all + registered VMs and associated snapshots: + </para> + +<screen>$ vboximg-mount --list --verbose + + ------------------------------------------------------ + VM Name: "macOS High Sierra 10.13" + UUID: 3887d96d-831c-4187-a55a-567c504ff0e1 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vbox + ----------------------- + HDD base: "macOS High Sierra 10.13.vdi" + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + + Diff 1: + UUID: 98c2bac9-cf37-443d-a935-4e879b70166d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{98c2bac9-cf37-443d-a935-4e879b70166d}.vdi + Diff 2: + UUID: f401f381-7377-40b3-948e-3c61241b1a42 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{f401f381-7377-40b3-948e-3c61241b1a42}.vdi + ----------------------- + HDD base: "simple_fixed_disk.vdi" + UUID: ffba4d7e-1277-489d-8173-22ca7660773d + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/simple_fixed_disk.vdi + + Diff 1: + UUID: aecab681-0d2d-468b-8682-93f79dc97a48 + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{aecab681-0d2d-468b-8682-93f79dc97a48}.vdi + Diff 2: + UUID: 70d6b34d-8422-47fa-8521-3b6929a1971c + Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/ + Snapshots/{70d6b34d-8422-47fa-8521-3b6929a1971c}.vdi + ------------------------------------------------------ + VM Name: "debian" + UUID: 5365ab5f-470d-44c0-9863-dad532ee5905 + Location: /Volumes/work/vm_guests/debian/debian.vbox + ----------------------- + HDD base: "debian.vdi" + UUID: 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7 + Location: /Volumes/work/vm_guests/debian/ol7.vdi + + Diff 1: + UUID: f9cc866a-9166-42e9-a503-bbfe9b7312e8 + Location: /Volumes/work/vm_guests/debian/Snapshots/ + {f9cc866a-9166-42e9-a503-bbfe9b7312e8}.vdi</screen> + + <para> + The following command outputs partition information about the + specified disk image: + </para> + +<screen>$ vboximg-mount --image=f9ea7173-6869-4aa9-b487-68023a655980 --list + + Virtual disk image: + + Path: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi + UUID: f9ea7173-6869-4aa9-b487-68023a655980 + + # Start Sectors Size Offset Type + 1 40 409599 199.9M 20480 EFI System + 2 409640 67453071 32.1G 209735680 Hierarchical File System Plus (HFS+) + 3 67862712 1269535 107.8M 34745708544 Apple Boot (Recovery HD)</screen> + + </sect2> + + <sect2 id="vboximg-mount-steps"> + + <title>Mounting a Virtual Disk Image</title> + + <para> + The following steps show how to use the + <command>vboximg-mount</command> command to mount a partition of + a virtual disk image on the host OS. + </para> + + <orderedlist> + + <listitem> + <para> + Create a mount point on the host OS. For example: + </para> + +<screen>$ mkdir macos_sysdisk</screen> + </listitem> + + <listitem> + <para> + Show partition information about the virtual disk image. + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> --list</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID of the + disk image. + </para> + </listitem> + + <listitem> + <para> + Use <command>vboximg-mount</command> to perform a FUSE mount + of a partition on the virtual disk image. For example: + </para> + +<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> -p 2 macos_sysdisk</screen> + + <para> + where <replaceable>uuid</replaceable> is the UUID for the + disk image. + </para> + + <para> + In this example, partition 2 is mounted on the + <filename>macos_sysdisk</filename> mount point. The mount + includes all snapshots for the disk image. + </para> + </listitem> + + <listitem> + <para> + Use the host OS to mount the <literal>vhdd</literal> device + node. The FUSE-mounted device node represents the virtual + disk image. + </para> + +<screen>$ ls macos_sysdisk + macOS High Sierra 10.13.vdi vhdd +$ sudo mount macos_sysdisk/vhdd /mnt</screen> + </listitem> + + </orderedlist> + + </sect2> + + </sect1> + +</chapter> |