VirtualBox

source: vbox/trunk/doc/manual/en_US/user_Storage.xml@ 79829

Last change on this file since 79829 was 76788, checked in by vboxsync, 6 years ago

doc/manual: eliminate tab, and make directory name macos_sysdisk consistently lowercase everywhere for consistency reasons (could be also called macOS_sysdisk, but again consistently)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 62.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
4<!ENTITY % all.entities SYSTEM "all-entities.ent">
5%all.entities;
6]>
7<chapter id="storage">
8
9 <title>Virtual Storage</title>
10
11 <para>
12 As the virtual machine will most probably expect to see a hard disk
13 built into its virtual computer, &product-name; must be able to
14 present real storage to the guest as a virtual hard disk. There are
15 presently three methods by which to achieve this:
16 </para>
17
18 <itemizedlist>
19
20 <listitem>
21 <para>
22 &product-name; can use large image files on a real hard disk and
23 present them to a guest as a virtual hard disk. This is the most
24 common method, described in <xref linkend="vdidetails" />.
25 </para>
26 </listitem>
27
28 <listitem>
29 <para>
30 iSCSI storage servers can be attached to &product-name;. This is
31 described in <xref linkend="storage-iscsi" />.
32 </para>
33 </listitem>
34
35 <listitem>
36 <para>
37 You can allow a virtual machine to access one of your host disks
38 directly. This is an advanced feature, described in
39 <xref linkend="rawdisk" />.
40 </para>
41 </listitem>
42
43 </itemizedlist>
44
45 <para>
46 Each such virtual storage device, such as an image file, iSCSI
47 target, or physical hard disk, needs to be connected to the virtual
48 hard disk controller that &product-name; presents to a virtual
49 machine. This is explained in the next section.
50 </para>
51
52 <sect1 id="harddiskcontrollers">
53
54 <title>Hard Disk Controllers: IDE, SATA (AHCI), SCSI, SAS, USB MSD, NVMe</title>
55
56 <para>
57 In a real PC, hard disks and CD/DVD drives are connected to a
58 device called hard disk controller which drives hard disk
59 operation and data transfers. &product-name; can emulate the five
60 most common types of hard disk controllers typically found in
61 today's PCs: IDE, SATA (AHCI), SCSI, SAS, USB-based, and NVMe mass
62 storage devices.
63 </para>
64
65 <itemizedlist>
66
67 <listitem>
68 <para>
69 <emphasis role="bold">IDE (ATA)</emphasis> controllers are a
70 backwards compatible yet very advanced extension of the disk
71 controller in the IBM PC/AT (1984). Initially, this interface
72 worked only with hard disks, but was later extended to also
73 support CD-ROM drives and other types of removable media. In
74 physical PCs, this standard uses flat ribbon parallel cables
75 with 40 or 80 wires. Each such cable can connect two devices
76 to a controller, which have traditionally been called
77 <emphasis>master</emphasis> and <emphasis>slave</emphasis>.
78 Typical PCs had two connectors for such cables. As a result,
79 support for up to four IDE devices was most common.
80 </para>
81
82 <para>
83 In &product-name;, each virtual machine may have one IDE
84 controller enabled, which gives you up to four virtual storage
85 devices that you can attach to the machine. By default, one of
86 these virtual storage devices, the secondary master, is
87 preconfigured to be the virtual machine's virtual CD/DVD
88 drive. However, you can change the default setting.
89 </para>
90
91 <para>
92 Even if your guest OS has no support for SCSI or SATA devices,
93 it should always be able to see an IDE controller.
94 </para>
95
96 <para>
97 You can also select which exact type of IDE controller
98 hardware &product-name; should present to the virtual machine:
99 PIIX3, PIIX4, or ICH6. This makes no difference in terms of
100 performance, but if you import a virtual machine from another
101 virtualization product, the OS in that machine may expect a
102 particular controller type and crash if it is not found.
103 </para>
104
105 <para>
106 After you have created a new virtual machine with the
107 <emphasis role="bold">New Virtual Machine</emphasis> wizard of
108 the graphical user interface, you will typically see one IDE
109 controller in the machine's
110 <emphasis role="bold">Storage</emphasis> settings. The virtual
111 CD/DVD drive will be attached to one of the four ports of this
112 controller.
113 </para>
114 </listitem>
115
116 <listitem>
117 <para>
118 <emphasis role="bold">Serial ATA (SATA)</emphasis> is a newer
119 standard introduced in 2003. Compared to IDE, it supports both
120 much higher speeds and more devices per controller. Also, with
121 physical hardware, devices can be added and removed while the
122 system is running. The standard interface for SATA controllers
123 is called Advanced Host Controller Interface (AHCI).
124 </para>
125
126 <para>
127 Like a real SATA controller, &product-name;'s virtual SATA
128 controller operates faster and also consumes fewer CPU
129 resources than the virtual IDE controller. Also, this enables
130 you to connect up to 30 virtual hard disks to one machine
131 instead of just three, when compared to the &product-name; IDE
132 controller with a DVD drive attached.
133 </para>
134
135 <para>
136 For this reason, depending on the selected guest OS,
137 &product-name; uses SATA as the default for newly created
138 virtual machines. One virtual SATA controller is created by
139 default, and the default disk that is created with a new VM is
140 attached to this controller.
141 </para>
142
143 <warning>
144 <para>
145 The entire SATA controller and the virtual disks attached to
146 it, including those in IDE compatibility mode, will not be
147 seen by OSes that do not have device support for AHCI. In
148 particular, <emphasis>there is no support for AHCI in
149 Windows before Windows Vista</emphasis>. So Windows XP, even
150 SP3, will not see such disks unless you install additional
151 drivers. It is possible to switch from IDE to SATA after
152 installation by installing the SATA drivers and changing the
153 controller type in the VM
154 <emphasis role="bold">Settings</emphasis> dialog.
155 </para>
156
157 <para>
158 &product-name; recommends the Intel Matrix Storage drivers,
159 which can be downloaded from
160 <ulink
161 url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101">http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101</ulink>.
162 </para>
163 </warning>
164
165 <para>
166 To add a SATA controller to a machine for which it has not
167 been enabled by default, either because it was created by an
168 earlier version of &product-name;, or because SATA is not
169 supported by default by the selected guest OS, do the
170 following. Go to the <emphasis role="bold">Storage</emphasis>
171 page of the machine's
172 <emphasis role="bold">Settings</emphasis> dialog, click
173 <emphasis role="bold">Add Controller</emphasis> under the
174 Storage Tree box and then select <emphasis role="bold">Add
175 SATA Controller</emphasis>. The new controller appears as a
176 separate PCI device in the virtual machine, and you can add
177 virtual disks to it.
178 </para>
179
180 <para>
181 To change the IDE compatibility mode settings for the SATA
182 controller, see <xref linkend="vboxmanage-storagectl" />.
183 </para>
184 </listitem>
185
186 <listitem>
187 <para>
188 <emphasis role="bold">SCSI</emphasis> is another established
189 industry standard, standing for Small Computer System
190 Interface. SCSI was standardized as early as 1986 as a generic
191 interface for data transfer between all kinds of devices,
192 including storage devices. Today SCSI is still used for
193 connecting hard disks and tape devices, but it has mostly been
194 displaced in commodity hardware. It is still in common use in
195 high-performance workstations and servers.
196 </para>
197
198 <para>
199 Primarily for compatibility with other virtualization
200 software, &product-name; optionally supports LSI Logic and
201 BusLogic SCSI controllers, to each of which up to 15 virtual
202 hard disks can be attached.
203 </para>
204
205 <para>
206 To enable a SCSI controller, on the
207 <emphasis role="bold">Storage</emphasis> page of a virtual
208 machine's <emphasis role="bold">Settings</emphasis> dialog,
209 click <emphasis role="bold">Add Controller</emphasis> under
210 the Storage Tree box and then select <emphasis role="bold">Add
211 SCSI Controller</emphasis>. The new controller appears as a
212 separate PCI device in the virtual machine.
213 </para>
214
215 <warning>
216 <para>
217 As with the other controller types, a SCSI controller will
218 only be seen by OSes with device support for it. Windows
219 2003 and later ships with drivers for the LSI Logic
220 controller, while Windows NT 4.0 and Windows 2000 ships with
221 drivers for the BusLogic controller. Windows XP ships with
222 drivers for neither.
223 </para>
224 </warning>
225 </listitem>
226
227 <listitem>
228 <para>
229 <emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is
230 another bus standard which uses the SCSI command set. As
231 opposed to SCSI, however, with physical devices, serial cables
232 are used instead of parallel ones, which simplifies physical
233 device connections. In some ways, therefore, SAS is to SCSI
234 what SATA is to IDE: it enables more reliable and faster
235 connections.
236 </para>
237
238 <para>
239 To support high-end guests which require SAS controllers,
240 &product-name; emulates a LSI Logic SAS controller, which can
241 be enabled much the same way as a SCSI controller. At this
242 time, up to eight devices can be connected to the SAS
243 controller.
244 </para>
245
246 <warning>
247 <para>
248 As with SATA, the SAS controller will only be seen by OSes
249 with device support for it. In particular, <emphasis>there
250 is no support for SAS in Windows before Windows
251 Vista</emphasis>. So Windows XP, even SP3, will not see such
252 disks unless you install additional drivers.
253 </para>
254 </warning>
255 </listitem>
256
257 <listitem>
258 <para>
259 The <emphasis role="bold">USB mass storage device
260 class</emphasis> is a standard to connect external storage
261 devices like hard disks or flash drives to a host through USB.
262 All major OSes support these devices for a long time and ship
263 generic drivers making third-party drivers superfluous. In
264 particular, legacy OSes without support for SATA controllers
265 may benefit from USB mass storage devices.
266 </para>
267
268 <para>
269 The virtual USB storage controller offered by &product-name;
270 works differently to the other storage controller types. While
271 most storage controllers appear as a single PCI device to the
272 guest with multiple disks attached to it, the USB-based
273 storage controller does not appear as virtual storage
274 controller. Each disk attached to the controller appears as a
275 dedicated USB device to the guest.
276 </para>
277
278 <warning>
279 <para>
280 Booting from drives attached using USB is only supported
281 when EFI is used as the BIOS lacks USB support.
282 </para>
283 </warning>
284 </listitem>
285
286 <listitem>
287 <para>
288 <emphasis role="bold">Non volatile memory express
289 (NVMe)</emphasis> is a standard which emerged in 2011 for
290 connecting non volatile memory (NVM) directly over PCI express
291 to lift the bandwidth limitation of the previously used SATA
292 protocol for SSDs. Unlike other standards the command set is
293 very simple to achieve maximum throughput and is not
294 compatible with ATA or SCSI. OSes need to support NVMe devices
295 to make use of them. For example, Windows 8.1 added native
296 NVMe support. For Windows 7, native support was added with an
297 update.
298 </para>
299
300 <para>
301 The NVMe controller is part of the extension pack.
302 </para>
303
304 <warning>
305 <para>
306 Booting from drives attached using NVMe is only supported
307 when EFI is used as the BIOS lacks the appropriate driver.
308 </para>
309 </warning>
310 </listitem>
311
312 </itemizedlist>
313
314 <para>
315 In summary, &product-name; gives you the following categories of
316 virtual storage slots:
317 </para>
318
319 <itemizedlist>
320
321 <listitem>
322 <para>
323 Four slots attached to the traditional IDE controller, which
324 are always present. One of these is typically a virtual CD/DVD
325 drive.
326 </para>
327 </listitem>
328
329 <listitem>
330 <para>
331 30 slots attached to the SATA controller, if enabled and
332 supported by the guest OS.
333 </para>
334 </listitem>
335
336 <listitem>
337 <para>
338 15 slots attached to the SCSI controller, if enabled and
339 supported by the guest OS.
340 </para>
341 </listitem>
342
343 <listitem>
344 <para>
345 Eight slots attached to the SAS controller, if enabled and
346 supported by the guest OS.
347 </para>
348 </listitem>
349
350 <listitem>
351 <para>
352 Eight slots attached to the virtual USB controller, if enabled
353 and supported by the guest OS.
354 </para>
355 </listitem>
356
357 <listitem>
358 <para>
359 Up to 255 slots attached to the NVMe controller, if enabled
360 and supported by the guest OS.
361 </para>
362 </listitem>
363
364 </itemizedlist>
365
366 <para>
367 Given this large choice of storage controllers, you may not know
368 which one to choose. In general, you should avoid IDE unless it is
369 the only controller supported by your guest. Whether you use SATA,
370 SCSI, or SAS does not make any real difference. The variety of
371 controllers is only supplied by &product-name; for compatibility
372 with existing hardware and other hypervisors.
373 </para>
374
375 </sect1>
376
377 <sect1 id="vdidetails">
378
379 <title>Disk Image Files (VDI, VMDK, VHD, HDD)</title>
380
381 <para>
382 Disk image files reside on the host system and are seen by the
383 guest systems as hard disks of a certain geometry. When a guest OS
384 reads from or writes to a hard disk, &product-name; redirects the
385 request to the image file.
386 </para>
387
388 <para>
389 Like a physical disk, a virtual disk has a size, or capacity,
390 which must be specified when the image file is created. As opposed
391 to a physical disk however, &product-name; enables you to expand
392 an image file after creation, even if it has data already. See
393 <xref linkend="vboxmanage-modifyvdi" />.
394 </para>
395
396 <para>
397 &product-name; supports the following types of disk image files:
398 </para>
399
400 <itemizedlist>
401
402 <listitem>
403 <para>
404 <emphasis role="bold">VDI.</emphasis> Normally, &product-name;
405 uses its own container format for guest hard disks. This is
406 called a Virtual Disk Image (VDI) file. This format is used
407 when you create a new virtual machine with a new disk.
408 </para>
409 </listitem>
410
411 <listitem>
412 <para>
413 <emphasis role="bold">VMDK.</emphasis> &product-name; also
414 fully supports the popular and open VMDK container format that
415 is used by many other virtualization products, such as VMware.
416 </para>
417 </listitem>
418
419 <listitem>
420 <para>
421 <emphasis role="bold">VHD.</emphasis> &product-name; also
422 fully supports the VHD format used by Microsoft.
423 </para>
424 </listitem>
425
426 <listitem>
427 <para>
428 <emphasis role="bold">HDD.</emphasis> Image files of Parallels
429 version 2 (HDD format) are also supported.
430 </para>
431
432 <para>
433 Due to lack of documentation of the format, newer versions
434 such as 3 and 4 are not supported. You can however convert
435 such image files to version 2 format using tools provided by
436 Parallels.
437 </para>
438 </listitem>
439
440 </itemizedlist>
441
442 <para>
443 Irrespective of the disk capacity and format, as mentioned in
444 <xref linkend="gui-createvm" />, there are two options for
445 creating a disk image: fixed-size or dynamically allocated.
446 </para>
447
448 <itemizedlist>
449
450 <listitem>
451 <para>
452 <emphasis role="bold">Fixed-size.</emphasis> If you create a
453 fixed-size image, an image file will be created on your host
454 system which has roughly the same size as the virtual disk's
455 capacity. So, for a 10 GB disk, you will have a 10 GB file.
456 Note that the creation of a fixed-size image can take a long
457 time depending on the size of the image and the write
458 performance of your hard disk.
459 </para>
460 </listitem>
461
462 <listitem>
463 <para>
464 <emphasis role="bold">Dynamically allocated.</emphasis> For
465 more flexible storage management, use a dynamically allocated
466 image. This will initially be very small and not occupy any
467 space for unused virtual disk sectors, but will grow every
468 time a disk sector is written to for the first time, until the
469 drive reaches the maximum capacity chosen when the drive was
470 created. While this format takes less space initially, the
471 fact that &product-name; needs to expand the image file
472 consumes additional computing resources, so until the disk
473 file size has stabilized, write operations may be slower than
474 with fixed size disks. However, after a time the rate of
475 growth will slow and the average penalty for write operations
476 will be negligible.
477 </para>
478 </listitem>
479
480 </itemizedlist>
481
482 </sect1>
483
484 <sect1 id="vdis">
485
486 <title>The Virtual Media Manager</title>
487
488 <para>
489 &product-name; keeps track of all the hard disk, CD/DVD-ROM, and
490 floppy disk images which are in use by virtual machines. These are
491 often referred to as <emphasis>known media</emphasis> and come
492 from two sources:
493 </para>
494
495 <itemizedlist>
496
497 <listitem>
498 <para>
499 All media currently attached to virtual machines.
500 </para>
501 </listitem>
502
503 <listitem>
504 <para>
505 Registered media, for compatibility with &product-name;
506 versions older than version 4.0. For details about how media
507 registration has changed with version 4.0, see
508 <xref linkend="vboxconfigdata" />.
509 </para>
510 </listitem>
511
512 </itemizedlist>
513
514 <para>
515 The known media can be viewed and changed using the
516 <emphasis role="bold">Virtual Media Manager</emphasis>, which you
517 can access from the <emphasis role="bold">File</emphasis> menu in
518 the VirtualBox Manager window.
519 </para>
520
521 <figure id="fig-virtual-media-manager">
522 <title>The Virtual Media Manager</title>
523 <mediaobject>
524 <imageobject>
525 <imagedata align="center" fileref="images/virtual-disk-manager.png"
526 width="12cm" />
527 </imageobject>
528 </mediaobject>
529 </figure>
530
531 <para>
532 The known media are conveniently grouped in separate tabs for the
533 supported formats. These formats are:
534 </para>
535
536 <itemizedlist>
537
538 <listitem>
539 <para>
540 Hard disk images, either in &product-name;'s own Virtual Disk
541 Image (VDI) format, or in the third-party formats listed in
542 <xref linkend="vdidetails"/>.
543 </para>
544 </listitem>
545
546 <listitem>
547 <para>
548 CD/DVD images in standard ISO format.
549 </para>
550 </listitem>
551
552 <listitem>
553 <para>
554 Floppy images in standard RAW format.
555 </para>
556 </listitem>
557
558 </itemizedlist>
559
560 <para>
561 For each image, the Virtual Media Manager shows you the full path
562 of the image file and other information, such as the virtual
563 machine the image is currently attached to.
564 </para>
565
566 <para>
567 The Virtual Media Manager enables you to do the following:
568 </para>
569
570 <itemizedlist>
571
572 <listitem>
573 <para>
574 <emphasis role="bold">Add</emphasis> an image to the registry.
575 </para>
576 </listitem>
577
578 <listitem>
579 <para>
580 <emphasis role="bold">Copy</emphasis> a virtual hard disk to
581 create another one.
582 </para>
583
584 <para>
585 You can specify one of the following target types: VDI, VHD,
586 or VMDK.
587 </para>
588 </listitem>
589
590 <listitem>
591 <para>
592 <emphasis role="bold">Move</emphasis> an image that is
593 currently in the registry to another location.
594 </para>
595
596 <para>
597 A file dialog prompts you for the new image file location.
598 </para>
599
600 <para>
601 When you use the Virtual Media Manager to move a disk image,
602 &product-name; updates all related configuration files
603 automatically.
604 </para>
605
606 <note>
607 <para>
608 Always use the Virtual Media Manager or the
609 <command>VBoxManage modifymedium</command> command to move a
610 disk image.
611 </para>
612
613 <para>
614 If you use a file management feature of the host OS to move
615 a disk image to a new location, run the <command>VBoxManage
616 modifymedium</command> <option>--setlocation</option>
617 command to configure the new path of the disk image on the
618 host file system. This command updates the &product-name;
619 configuration automatically.
620 </para>
621 </note>
622 </listitem>
623
624 <listitem>
625 <para>
626 <emphasis role="bold">Remove</emphasis> an image from the
627 registry. You can optionally delete the image file when
628 removing the image.
629 </para>
630 </listitem>
631
632 <listitem>
633 <para>
634 <emphasis role="bold">Release</emphasis> an image to detach it
635 from a VM. This action only applies if the image is currently
636 attached to a VM as a virtual hard disk.
637 </para>
638 </listitem>
639
640 <listitem>
641 <para>
642 View and edit the <emphasis role="bold">Properties</emphasis>
643 of a disk image.
644 </para>
645
646 <para>
647 Available properties include the following:
648 </para>
649
650 <itemizedlist>
651
652 <listitem>
653 <para>
654 <emphasis role="bold">Type:</emphasis> Specifies the
655 snapshot behavior of the disk. See
656 <xref linkend="hdimagewrites"/>.
657 </para>
658 </listitem>
659
660 <listitem>
661 <para>
662 <emphasis role="bold">Location:</emphasis> Specifies the
663 location of the disk image file on the host system. You
664 can use a file dialog to browse for the disk image
665 location.
666 </para>
667 </listitem>
668
669 <listitem>
670 <para>
671 <emphasis role="bold">Description:</emphasis> Specifies a
672 short description of the disk image.
673 </para>
674 </listitem>
675
676 <listitem>
677 <para>
678 <emphasis role="bold">Size:</emphasis> Specifies the size
679 of the disk image. You can use the slider to increase or
680 decrease the disk image size.
681 </para>
682 </listitem>
683
684 <listitem>
685 <para>
686 <emphasis role="bold">Information:</emphasis> Specifies
687 detailed information about the disk image.
688 </para>
689 </listitem>
690
691 </itemizedlist>
692 </listitem>
693
694 <listitem>
695 <para>
696 <emphasis role="bold">Refresh</emphasis> the property values
697 of the selected disk image.
698 </para>
699 </listitem>
700
701 </itemizedlist>
702
703 <para>
704 To perform these actions, highlight the medium in the Virtual
705 Media Manager and then do one of the following:
706 </para>
707
708 <itemizedlist>
709
710 <listitem>
711 <para>
712 Click an icon in the Virtual Media Manager task bar.
713 </para>
714 </listitem>
715
716 <listitem>
717 <para>
718 Right-click the medium and select an option.
719 </para>
720 </listitem>
721
722 </itemizedlist>
723
724 <para>
725 Use the <emphasis role="bold">Storage</emphasis> page in a VM's
726 <emphasis role="bold">Settings</emphasis> dialog to create a new
727 disk image. By default, disk images are stored in the VM's folder.
728 </para>
729
730 <para>
731 You can copy hard disk image files to other host systems and
732 import them in to VMs from the host system. However, certain guest
733 OSes, such as Windows 2000 and Windows XP, require that you
734 configure the new VM in a similar way to the old one.
735 </para>
736
737 <note>
738 <para>
739 Do not simply make copies of virtual disk images. If you import
740 such a second copy into a VM, &product-name; issues an error
741 because &product-name; assigns a universally unique identifier
742 (UUID) to each disk image to ensure that it is only used one
743 time. See <xref linkend="cloningvdis" />. Also, if you want to
744 copy a VM to another system, use the &product-name; import and
745 export features. See <xref linkend="ovf" />.
746 </para>
747 </note>
748
749 </sect1>
750
751 <sect1 id="hdimagewrites">
752
753 <title>Special Image Write Modes</title>
754
755 <para>
756 For each virtual disk image supported by &product-name;, you can
757 determine separately how it should be affected by write operations
758 from a virtual machine and snapshot operations. This applies to
759 all of the aforementioned image formats (VDI, VMDK, VHD, or HDD)
760 and irrespective of whether an image is fixed-size or dynamically
761 allocated.
762 </para>
763
764 <para>
765 By default, images are in <emphasis>normal</emphasis> mode. To
766 mark an existing image with one of the non-standard modes listed
767 below, use <command>VBoxManage modifyhd</command>. See
768 <xref linkend="vboxmanage-modifyvdi" />. Alternatively, use
769 <command>VBoxManage</command> to attach the image to a VM and use
770 the <option>--mtype</option> argument. See
771 <xref linkend="vboxmanage-storageattach" />.
772 </para>
773
774 <para>
775 The available virtual disk image modes are as follows:
776 </para>
777
778 <itemizedlist>
779
780 <listitem>
781 <para>
782 <emphasis role="bold">Normal images</emphasis> have no
783 restrictions on how guests can read from and write to the
784 disk. This is the default image mode.
785 </para>
786
787 <para>
788 When you take a snapshot of your virtual machine as described
789 in <xref linkend="snapshots" />, the state of a normal hard
790 disk is recorded together with the snapshot, and when
791 reverting to the snapshot, its state will be fully reset.
792 </para>
793
794 <para>
795 The image file itself is not reset. Instead, when a snapshot
796 is taken, &product-name; "freezes" the image file and no
797 longer writes to it. For the write operations from the VM, a
798 second, <emphasis>differencing</emphasis> image file is
799 created which receives only the changes to the original image.
800 See <xref linkend="diffimages"/>.
801 </para>
802
803 <para>
804 While you can attach the same normal image to more than one
805 virtual machine, only one of these virtual machines attached
806 to the same image file can be executed simultaneously, as
807 otherwise there would be conflicts if several machines write
808 to the same image file.
809 </para>
810 </listitem>
811
812 <listitem>
813 <para>
814 <emphasis role="bold">Write-through hard disks</emphasis> are
815 completely unaffected by snapshots. Their state is
816 <emphasis>not</emphasis> saved when a snapshot is taken, and
817 not restored when a snapshot is restored.
818 </para>
819 </listitem>
820
821 <listitem>
822 <para>
823 <emphasis role="bold">Shareable hard disks</emphasis> are a
824 variant of write-through hard disks. In principle they behave
825 exactly the same. Their state is <emphasis>not</emphasis>
826 saved when a snapshot is taken, and not restored when a
827 snapshot is restored. The difference only shows if you attach
828 such disks to several VMs. Shareable disks may be attached to
829 several VMs which may run concurrently. This makes them
830 suitable for use by cluster filesystems between VMs and
831 similar applications which are explicitly prepared to access a
832 disk concurrently. Only fixed size images can be used in this
833 way, and dynamically allocated images are rejected.
834 </para>
835
836 <warning>
837 <para>
838 This is an expert feature, and misuse can lead to data loss,
839 as regular filesystems are not prepared to handle
840 simultaneous changes by several parties.
841 </para>
842 </warning>
843 </listitem>
844
845 <listitem>
846 <para>
847 <emphasis role="bold">Immutable images</emphasis> only
848 remember write accesses temporarily while the virtual machine
849 is running. All changes are lost when the virtual machine is
850 powered on the next time. As a result, as opposed to Normal
851 images, the same immutable image can be used with several
852 virtual machines without restrictions.
853 </para>
854
855 <para>
856 Creating an immutable image makes little sense since it would
857 be initially empty and lose its contents with every machine
858 restart. You would have a disk that is always unformatted when
859 the machine starts up. Instead, you can first create a normal
860 image and then later mark it as immutable when you decide that
861 the contents are useful.
862 </para>
863
864 <para>
865 If you take a snapshot of a machine with immutable images,
866 then on every machine power-up, those images are reset to the
867 state of the last (current) snapshot, instead of the state of
868 the original immutable image.
869 </para>
870
871 <note>
872 <para>
873 As a special exception, immutable images are
874 <emphasis>not</emphasis> reset if they are attached to a
875 machine in a saved state or whose last snapshot was taken
876 while the machine was running. This is called an
877 <emphasis>online snapshot</emphasis>. As a result, if the
878 machine's current snapshot is an online snapshot, its
879 immutable images behave exactly like the a normal image. To
880 reenable the automatic resetting of such images, delete the
881 current snapshot of the machine.
882 </para>
883 </note>
884
885 <para>
886 &product-name; never writes to an immutable image directly at
887 all. All write operations from the machine are directed to a
888 differencing image. The next time the VM is powered on, the
889 differencing image is reset so that every time the VM starts,
890 its immutable images have exactly the same content.
891 </para>
892
893 <para>
894 The differencing image is only reset when the machine is
895 powered on from within &product-name;, not when you reboot by
896 requesting a reboot from within the machine. This is also why
897 immutable images behave as described above when snapshots are
898 also present, which use differencing images as well.
899 </para>
900
901 <para>
902 If the automatic discarding of the differencing image on VM
903 startup does not fit your needs, you can turn it off using the
904 <option>autoreset</option> parameter of <command>VBoxManage
905 modifyhd</command>. See
906 <xref linkend="vboxmanage-modifyvdi"/>.
907 </para>
908 </listitem>
909
910 <listitem>
911 <para>
912 <emphasis role="bold">Multiattach mode images</emphasis> can
913 be attached to more than one virtual machine at the same time,
914 even if these machines are running simultaneously. For each
915 virtual machine to which such an image is attached, a
916 differencing image is created. As a result, data that is
917 written to such a virtual disk by one machine is not seen by
918 the other machines to which the image is attached. Each
919 machine creates its own write history of the multiattach
920 image.
921 </para>
922
923 <para>
924 Technically, a multiattach image behaves identically to an
925 immutable image except the differencing image is not reset
926 every time the machine starts.
927 </para>
928
929 <para>
930 This mode is useful for sharing files which are almost never
931 written, for instance picture galleries, where every guest
932 changes only a small amount of data and the majority of the
933 disk content remains unchanged. The modified blocks are stored
934 in differencing images which remain relatively small and the
935 shared content is stored only once at the host.
936 </para>
937 </listitem>
938
939 <listitem>
940 <para>
941 <emphasis role="bold">Read-only images</emphasis> are used
942 automatically for CD/DVD images, since CDs/DVDs can never be
943 written to.
944 </para>
945 </listitem>
946
947 </itemizedlist>
948
949 <para>
950 The following scenario illustrates the differences between the
951 various image modes, with respect to snapshots.
952 </para>
953
954 <para>
955 Assume you have installed your guest OS in your VM, and you have
956 taken a snapshot. Later, your VM is infected with a virus and you
957 would like to go back to the snapshot. With a normal hard disk
958 image, you simply restore the snapshot, and the earlier state of
959 your hard disk image will be restored as well and your virus
960 infection will be undone. With an immutable hard disk, all it
961 takes is to shut down and power on your VM, and the virus
962 infection will be discarded. With a write-through image however,
963 you cannot easily undo the virus infection by means of
964 virtualization, but will have to disinfect your virtual machine
965 like a real computer.
966 </para>
967
968 <para>
969 You might find write-through images useful if you want to preserve
970 critical data irrespective of snapshots. As you can attach more
971 than one image to a VM, you may want to have one immutable image
972 for the OS and one write-through image for your data files.
973 </para>
974
975 </sect1>
976
977 <sect1 id="diffimages">
978
979 <title>Differencing Images</title>
980
981 <para>
982 The previous section mentioned differencing images and how they
983 are used with snapshots, immutable images, and multiple disk
984 attachments. This section describes in more detail how
985 differencing images work.
986 </para>
987
988 <para>
989 A differencing image is a special disk image that only holds the
990 differences to another image. A differencing image by itself is
991 useless, it must always refer to another image. The differencing
992 image is then typically referred to as a
993 <emphasis>child</emphasis>, which holds the differences to its
994 <emphasis>parent</emphasis>.
995 </para>
996
997 <para>
998 When a differencing image is active, it receives all write
999 operations from the virtual machine instead of its parent. The
1000 differencing image only contains the sectors of the virtual hard
1001 disk that have changed since the differencing image was created.
1002 When the machine reads a sector from such a virtual hard disk, it
1003 looks into the differencing image first. If the sector is present,
1004 it is returned from there. If not, &product-name; looks into the
1005 parent. In other words, the parent becomes
1006 <emphasis>read-only</emphasis>. It is never written to again, but
1007 it is read from if a sector has not changed.
1008 </para>
1009
1010 <para>
1011 Differencing images can be chained. If another differencing image
1012 is created for a virtual disk that already has a differencing
1013 image, then it becomes a <emphasis>grandchild</emphasis> of the
1014 original parent. The first differencing image then becomes
1015 read-only as well, and write operations only go to the
1016 second-level differencing image. When reading from the virtual
1017 disk, &product-name; needs to look into the second differencing
1018 image first, then into the first if the sector was not found, and
1019 then into the original image.
1020 </para>
1021
1022 <para>
1023 There can be an unlimited number of differencing images, and each
1024 image can have more than one child. As a result, the differencing
1025 images can form a complex tree with parents, siblings, and
1026 children, depending on how complex your machine configuration is.
1027 Write operations always go to the one <emphasis>active</emphasis>
1028 differencing image that is attached to the machine, and for read
1029 operations, &product-name; may need to look up all the parents in
1030 the chain until the sector in question is found. You can view such
1031 a tree in the Virtual Media Manager.
1032 </para>
1033
1034 <figure id="fig-diff-images">
1035 <title>Differencing Images, Shown in Virtual Media Manager</title>
1036 <mediaobject>
1037 <imageobject>
1038 <imagedata align="center" fileref="images/virtual-disk-manager2.png"
1039 width="12cm" />
1040 </imageobject>
1041 </mediaobject>
1042 </figure>
1043
1044 <para>
1045 In all of these situations, from the point of view of the virtual
1046 machine, the virtual hard disk behaves like any other disk. While
1047 the virtual machine is running, there is a slight run-time I/O
1048 overhead because &product-name; might need to look up sectors
1049 several times. This is not noticeable however since the tables
1050 with sector information are always kept in memory and can be
1051 looked up quickly.
1052 </para>
1053
1054 <para>
1055 Differencing images are used in the following situations:
1056 </para>
1057
1058 <itemizedlist>
1059
1060 <listitem>
1061 <para>
1062 <emphasis role="bold">Snapshots.</emphasis> When you create a
1063 snapshot, as explained in the previous section, &product-name;
1064 "freezes" the images attached to the virtual machine and
1065 creates differencing images for each image that is not in
1066 "write-through" mode. From the point of view of the virtual
1067 machine, the virtual disks continue to operate before, but all
1068 write operations go into the differencing images. Each time
1069 you create another snapshot, for each hard disk attachment,
1070 another differencing image is created and attached, forming a
1071 chain or tree.
1072 </para>
1073
1074 <para>
1075 In the above screenshot, you see that the original disk image
1076 is now attached to a snapshot, representing the state of the
1077 disk when the snapshot was taken.
1078 </para>
1079
1080 <para>
1081 If you <emphasis>restore</emphasis> a snapshot, and want to go
1082 back to the exact machine state that was stored in the
1083 snapshot, the following happens:
1084 </para>
1085
1086 <itemizedlist>
1087
1088 <listitem>
1089 <para>
1090 &product-name; copies the virtual machine settings that
1091 were copied into the snapshot back to the virtual machine.
1092 As a result, if you have made changes to the machine
1093 configuration since taking the snapshot, they are undone.
1094 </para>
1095 </listitem>
1096
1097 <listitem>
1098 <para>
1099 If the snapshot was taken while the machine was running,
1100 it contains a saved machine state, and that state is
1101 restored as well. After restoring the snapshot, the
1102 machine will then be in Saved state and resume execution
1103 from there when it is next started. Otherwise the machine
1104 will be in Powered Off state and do a full boot.
1105 </para>
1106 </listitem>
1107
1108 <listitem>
1109 <para>
1110 For each disk image attached to the machine, the
1111 differencing image holding all the write operations since
1112 the current snapshot was taken is thrown away, and the
1113 original parent image is made active again. If you
1114 restored the root snapshot, then this will be the root
1115 disk image for each attachment. Otherwise, some other
1116 differencing image descended from it. This effectively
1117 restores the old machine state.
1118 </para>
1119 </listitem>
1120
1121 </itemizedlist>
1122
1123 <para>
1124 If you later <emphasis>delete</emphasis> a snapshot in order
1125 to free disk space, for each disk attachment, one of the
1126 differencing images becomes obsolete. In this case, the
1127 differencing image of the disk attachment cannot simply be
1128 deleted. Instead, &product-name; needs to look at each sector
1129 of the differencing image and needs to copy it back into its
1130 parent. This is called "merging" images and can be a
1131 potentially lengthy process, depending on how large the
1132 differencing image is. It can also temporarily need a
1133 considerable amount of extra disk space, before the
1134 differencing image obsoleted by the merge operation is
1135 deleted.
1136 </para>
1137 </listitem>
1138
1139 <listitem>
1140 <para>
1141 <emphasis role="bold">Immutable images.</emphasis> When an
1142 image is switched to immutable mode, a differencing image is
1143 created as well. As with snapshots, the parent image then
1144 becomes read-only, and the differencing image receives all the
1145 write operations. Every time the virtual machine is started,
1146 all the immutable images which are attached to it have their
1147 respective differencing image thrown away, effectively
1148 resetting the virtual machine's virtual disk with every
1149 restart.
1150 </para>
1151 </listitem>
1152
1153 </itemizedlist>
1154
1155 </sect1>
1156
1157 <sect1 id="cloningvdis">
1158
1159 <title>Cloning Disk Images</title>
1160
1161 <para>
1162 You can duplicate hard disk image files on the same host to
1163 quickly produce a second virtual machine with the same OS setup.
1164 However, you should <emphasis>only</emphasis> make copies of
1165 virtual disk images using the utility supplied with
1166 &product-name;. See <xref linkend="vboxmanage-clonevdi" />. This
1167 is because &product-name; assigns a UUID to each disk image, which
1168 is also stored inside the image, and &product-name; will refuse to
1169 work with two images that use the same number. If you do
1170 accidentally try to reimport a disk image which you copied
1171 normally, you can make a second copy using the <command>VBoxManage
1172 clonevm</command> command and import that instead.
1173 </para>
1174
1175 <para>
1176 Note that newer Linux distributions identify the boot hard disk
1177 from the ID of the drive. The ID &product-name; reports for a
1178 drive is determined from the UUID of the virtual disk image. So if
1179 you clone a disk image and try to boot the copied image the guest
1180 might not be able to determine its own boot disk as the UUID
1181 changed. In this case you have to adapt the disk ID in your boot
1182 loader script, for example
1183 <computeroutput>/boot/grub/menu.lst</computeroutput>. The disk ID
1184 looks like the following:
1185 </para>
1186
1187<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen>
1188
1189 <para>
1190 The ID for the copied image can be determined as follows:
1191 </para>
1192
1193<screen>hdparm -i /dev/sda</screen>
1194
1195 </sect1>
1196
1197 <sect1 id="iocaching">
1198
1199 <title>Host Input/Output Caching</title>
1200
1201 <para>
1202 &product-name; can optionally disable the I/O caching that the
1203 host OS would otherwise perform on disk image files.
1204 </para>
1205
1206 <para>
1207 Traditionally, &product-name; has opened disk image files as
1208 normal files, which results in them being cached by the host OS
1209 like any other file. The main advantage of this is speed: when the
1210 guest OS writes to disk and the host OS cache uses delayed
1211 writing, the write operation can be reported as completed to the
1212 guest OS quickly while the host OS can perform the operation
1213 asynchronously. Also, when you start a VM a second time and have
1214 enough memory available for the OS to use for caching, large parts
1215 of the virtual disk may be in system memory, and the VM can access
1216 the data much faster.
1217 </para>
1218
1219 <para>
1220 Note that this applies only to image files. Buffering does not
1221 occur for virtual disks residing on remote iSCSI storage, which is
1222 the more common scenario in enterprise-class setups. See
1223 <xref linkend="storage-iscsi" />.
1224 </para>
1225
1226 <para>
1227 While buffering is a useful default setting for virtualizing a few
1228 machines on a desktop computer, there are some disadvantages to
1229 this approach:
1230 </para>
1231
1232 <itemizedlist>
1233
1234 <listitem>
1235 <para>
1236 Delayed writing through the host OS cache is less secure. When
1237 the guest OS writes data, it considers the data written even
1238 though it has not yet arrived on a physical disk. If for some
1239 reason the write does not happen, such as power failure or
1240 host crash, the likelihood of data loss increases.
1241 </para>
1242 </listitem>
1243
1244 <listitem>
1245 <para>
1246 Disk image files tend to be very large. Caching them can
1247 therefore quickly use up the entire host OS cache. Depending
1248 on the efficiency of the host OS caching, this may slow down
1249 the host immensely, especially if several VMs run at the same
1250 time. For example, on Linux hosts, host caching may result in
1251 Linux delaying all writes until the host cache is nearly full
1252 and then writing out all these changes at once, possibly
1253 stalling VM execution for minutes. This can result in I/O
1254 errors in the guest as I/O requests time out there.
1255 </para>
1256 </listitem>
1257
1258 <listitem>
1259 <para>
1260 Physical memory is often wasted as guest OSes typically have
1261 their own I/O caches, which may result in the data being
1262 cached twice, in both the guest and the host caches, for
1263 little effect.
1264 </para>
1265 </listitem>
1266
1267 </itemizedlist>
1268
1269 <para>
1270 If you decide to disable host I/O caching for the above reasons,
1271 &product-name; uses its own small cache to buffer writes, but no
1272 read caching since this is typically already performed by the
1273 guest OS. In addition, &product-name; fully supports asynchronous
1274 I/O for its virtual SATA, SCSI, and SAS controllers through
1275 multiple I/O threads.
1276 </para>
1277
1278 <para>
1279 Since asynchronous I/O is not supported by IDE controllers, for
1280 performance reasons, you may want to leave host caching enabled
1281 for your VM's virtual IDE controllers.
1282 </para>
1283
1284 <para>
1285 For this reason, &product-name; enables you to configure whether
1286 the host I/O cache is used for each I/O controller separately.
1287 Either select the <emphasis role="bold">Use Host I/O
1288 Cache</emphasis> check box in the
1289 <emphasis role="bold">Storage</emphasis> settings for a given
1290 virtual storage controller, or use the following
1291 <command>VBoxManage</command> command to disable the host I/O
1292 cache for a virtual storage controller:
1293 </para>
1294
1295<screen>VBoxManage storagectl "VM name" --name &lt;controllername&gt; --hostiocache off</screen>
1296
1297 <para>
1298 See <xref linkend="vboxmanage-storagectl" />.
1299 </para>
1300
1301 <para>
1302 For the above reasons, &product-name; now uses SATA controllers by
1303 default for new virtual machines.
1304 </para>
1305
1306 </sect1>
1307
1308 <sect1 id="storage-bandwidth-limit">
1309
1310 <title>Limiting Bandwidth for Disk Images</title>
1311
1312 <para>
1313 &product-name; supports limiting of the maximum bandwidth used for
1314 asynchronous I/O. Additionally it supports sharing limits through
1315 bandwidth groups for several images. It is possible to have more
1316 than one such limit.
1317 </para>
1318
1319 <para>
1320 Limits are configured using <command>VBoxManage</command>. The
1321 example below creates a bandwidth group named Limit, sets the
1322 limit to 20 MB per second, and assigns the group to the attached
1323 disks of the VM:
1324 </para>
1325
1326<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M
1327VBoxManage storageattach "VM name" --storagectl "SATA" --port 0 --device 0 --type hdd
1328 --medium disk1.vdi --bandwidthgroup Limit
1329VBoxManage storageattach "VM name" --storagectl "SATA" --port 1 --device 0 --type hdd
1330 --medium disk2.vdi --bandwidthgroup Limit</screen>
1331
1332 <para>
1333 All disks in a group share the bandwidth limit, meaning that in
1334 the example above the bandwidth of both images combined can never
1335 exceed 20 MBps. However, if one disk does not require bandwidth
1336 the other can use the remaining bandwidth of its group.
1337 </para>
1338
1339 <para>
1340 The limits for each group can be changed while the VM is running,
1341 with changes being picked up immediately. The example below
1342 changes the limit for the group created in the example above to 10
1343 MBps:
1344 </para>
1345
1346<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen>
1347
1348 </sect1>
1349
1350 <sect1 id="storage-cds">
1351
1352 <title>CD/DVD Support</title>
1353
1354 <para>
1355 Virtual CD/DVD drives by default support only reading. The medium
1356 configuration is changeable at runtime. You can select between the
1357 following options to provide the medium data:
1358 </para>
1359
1360 <itemizedlist>
1361
1362 <listitem>
1363 <para>
1364 <emphasis role="bold">Host Drive</emphasis> defines that the
1365 guest can read from the medium in the host drive.
1366 </para>
1367 </listitem>
1368
1369 <listitem>
1370 <para>
1371 <emphasis role="bold">Image file</emphasis> gives the guest
1372 read-only access to the data in the image. This is typically
1373 an ISO file.
1374 </para>
1375 </listitem>
1376
1377 <listitem>
1378 <para>
1379 <emphasis role="bold">Empty</emphasis> means a drive without
1380 an inserted medium.
1381 </para>
1382 </listitem>
1383
1384 </itemizedlist>
1385
1386 <para>
1387 Changing between the above, or changing a medium in the host drive
1388 that is accessed by a machine, or changing an image file will
1389 signal a medium change to the guest OS. The guest OS can then
1390 react to the change, for example by starting an installation
1391 program.
1392 </para>
1393
1394 <para>
1395 Medium changes can be prevented by the guest, and &product-name;
1396 reflects that by locking the host drive if appropriate. You can
1397 force a medium removal in such situations by using the
1398 &product-name; GUI or the <command>VBoxManage</command> command
1399 line tool. Effectively this is the equivalent of the emergency
1400 eject which many CD/DVD drives provide, with all associated side
1401 effects. The guest OS can issue error messages, just like on real
1402 hardware, and guest applications may misbehave. Use this with
1403 caution.
1404 </para>
1405
1406 <note>
1407 <para>
1408 The identification string of the drive provided to the guest,
1409 displayed by configuration tools such as the Windows Device
1410 Manager, is always VBOX CD-ROM, irrespective of the current
1411 configuration of the virtual drive. This is to prevent hardware
1412 detection from being triggered in the guest OS every time the
1413 configuration is changed.
1414 </para>
1415 </note>
1416
1417 <para>
1418 The standard CD/DVD emulation enables reading of standard data CD
1419 and DVD formats only. As an experimental feature, for additional
1420 capabilities, it is possible to give the guest direct access to
1421 the CD/DVD host drive by enabling <emphasis>passthrough</emphasis>
1422 mode. Depending on the host hardware, this may potentially enable
1423 the following things to work:
1424 </para>
1425
1426 <itemizedlist>
1427
1428 <listitem>
1429 <para>
1430 CD/DVD writing from within the guest, if the host DVD drive is
1431 a CD/DVD writer
1432 </para>
1433 </listitem>
1434
1435 <listitem>
1436 <para>
1437 Playing audio CDs
1438 </para>
1439 </listitem>
1440
1441 <listitem>
1442 <para>
1443 Playing encrypted DVDs
1444 </para>
1445 </listitem>
1446
1447 </itemizedlist>
1448
1449 <para>
1450 There is a <emphasis role="bold">Passthrough</emphasis> check box
1451 in the GUI dialog for configuring the media attached to a storage
1452 controller, or you can use the <option>--passthrough</option>
1453 option with <command>VBoxManage storageattach</command>. See
1454 <xref linkend="vboxmanage-storageattach" />.
1455 </para>
1456
1457 <para>
1458 Even if passthrough is enabled, unsafe commands, such as updating
1459 the drive firmware, will be blocked. Video CD formats are never
1460 supported, not even in passthrough mode, and cannot be played from
1461 a virtual machine.
1462 </para>
1463
1464 <para>
1465 On Oracle Solaris hosts, passthrough requires running
1466 &product-name; with real root permissions due to security measures
1467 enforced by the host.
1468 </para>
1469
1470 </sect1>
1471
1472 <sect1 id="storage-iscsi">
1473
1474 <title>iSCSI Servers</title>
1475
1476 <para>
1477 iSCSI stands for "Internet SCSI" and is a standard that supports
1478 use of the SCSI protocol over Internet (TCP/IP) connections.
1479 Especially with the advent of Gigabit Ethernet, it has become
1480 affordable to attach iSCSI storage servers simply as remote hard
1481 disks to a computer network. In iSCSI terminology, the server
1482 providing storage resources is called an <emphasis>iSCSI
1483 target</emphasis>, while the client connecting to the server and
1484 accessing its resources is called an <emphasis>iSCSI
1485 initiator</emphasis>.
1486 </para>
1487
1488 <para>
1489 &product-name; can transparently present iSCSI remote storage to a
1490 virtual machine as a virtual hard disk. The guest OS will not see
1491 any difference between a virtual disk image (VDI file) and an
1492 iSCSI target. To achieve this, &product-name; has an integrated
1493 iSCSI initiator.
1494 </para>
1495
1496 <para>
1497 &product-name;'s iSCSI support has been developed according to the
1498 iSCSI standard and should work with all standard-conforming iSCSI
1499 targets. To use an iSCSI target with &product-name;, you must use
1500 the command line. See <xref linkend="vboxmanage-storageattach" />.
1501 </para>
1502
1503 </sect1>
1504
1505 <sect1 id="vboximg-mount">
1506
1507 <title>vboximg-mount: A Utility for FUSE Mounting a Virtual Disk Image</title>
1508
1509 <para>
1510 <command>vboximg-mount</command> is a command line utility for Mac
1511 OS X hosts that provides raw access to an &product-name; virtual
1512 disk image on the host system. Use this utility to mount, view,
1513 and optionally modify the disk image contents.
1514 </para>
1515
1516 <para>
1517 The utility is based on Filesystem in Userspace (FUSE) technology
1518 and uses the VirtualBox runtime engine. Ensure that &product-name;
1519 is running on the host system.
1520 </para>
1521
1522 <note>
1523 <para>
1524 When using <command>vboximg-mount</command>, ensure that the
1525 following conditions apply:
1526 </para>
1527
1528 <itemizedlist>
1529
1530 <listitem>
1531 <para>
1532 The disk image is not being used by any other systems, such
1533 as by guest VMs.
1534 </para>
1535 </listitem>
1536
1537 <listitem>
1538 <para>
1539 No VMs are running on the host system.
1540 </para>
1541 </listitem>
1542
1543 </itemizedlist>
1544 </note>
1545
1546 <para>
1547 Raw access using FUSE is preferred over direct loopback mounting
1548 of virtual disk images, because it is snapshot aware. It can
1549 selectively merge disk differencing images in an exposed virtual
1550 hard disk, providing historical or up-to-date representations of
1551 the virtual disk contents.
1552 </para>
1553
1554 <para>
1555 <command>vboximg-mount</command> enables you to view information
1556 about registered VMs, their attached disk media, and any
1557 snapshots. Also, you can view partition information for a disk
1558 image.
1559 </para>
1560
1561 <para>
1562 Use the <option>--help</option> option to view information about
1563 the <command>vboximg-mount</command> command usage.
1564 </para>
1565
1566 <para>
1567 When <command>vboximg-mount</command> mounts an &product-name;
1568 disk image, it creates a one level deep file system at a mount
1569 point that you specify. The file system includes a device node
1570 that represents the synthesized disk image as a readable or
1571 readable-writeable bytestream. This bytestream can be mounted
1572 either by using the host OS or by using other FUSE-based file
1573 systems.
1574 </para>
1575
1576 <sect2 id="vboximg-mount-display">
1577
1578 <title>Viewing Detailed Information About a Virtual Disk Image</title>
1579
1580 <para>
1581 The following examples show how to use the
1582 <command>vboximg-mount</command> command to view information
1583 about virtual disk images.
1584 </para>
1585
1586 <para>
1587 The following command outputs detailed information about all
1588 registered VMs and associated snapshots:
1589 </para>
1590
1591<screen>$ vboximg-mount --list --verbose
1592
1593 ------------------------------------------------------
1594 VM Name: "macOS High Sierra 10.13"
1595 UUID: 3887d96d-831c-4187-a55a-567c504ff0e1
1596 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vbox
1597 -----------------------
1598 HDD base: "macOS High Sierra 10.13.vdi"
1599 UUID: f9ea7173-6869-4aa9-b487-68023a655980
1600 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi
1601
1602 Diff 1:
1603 UUID: 98c2bac9-cf37-443d-a935-4e879b70166d
1604 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/
1605 Snapshots/{98c2bac9-cf37-443d-a935-4e879b70166d}.vdi
1606 Diff 2:
1607 UUID: f401f381-7377-40b3-948e-3c61241b1a42
1608 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/
1609 Snapshots/{f401f381-7377-40b3-948e-3c61241b1a42}.vdi
1610 -----------------------
1611 HDD base: "simple_fixed_disk.vdi"
1612 UUID: ffba4d7e-1277-489d-8173-22ca7660773d
1613 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/simple_fixed_disk.vdi
1614
1615 Diff 1:
1616 UUID: aecab681-0d2d-468b-8682-93f79dc97a48
1617 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/
1618 Snapshots/{aecab681-0d2d-468b-8682-93f79dc97a48}.vdi
1619 Diff 2:
1620 UUID: 70d6b34d-8422-47fa-8521-3b6929a1971c
1621 Location: /Volumes/work/vm_guests/macOS High Sierra 10.13/
1622 Snapshots/{70d6b34d-8422-47fa-8521-3b6929a1971c}.vdi
1623 ------------------------------------------------------
1624 VM Name: "debian"
1625 UUID: 5365ab5f-470d-44c0-9863-dad532ee5905
1626 Location: /Volumes/work/vm_guests/debian/debian.vbox
1627 -----------------------
1628 HDD base: "debian.vdi"
1629 UUID: 96d2e92e-0d4e-46ab-a0f1-008fdbf997e7
1630 Location: /Volumes/work/vm_guests/debian/ol7.vdi
1631
1632 Diff 1:
1633 UUID: f9cc866a-9166-42e9-a503-bbfe9b7312e8
1634 Location: /Volumes/work/vm_guests/debian/Snapshots/
1635 {f9cc866a-9166-42e9-a503-bbfe9b7312e8}.vdi</screen>
1636
1637 <para>
1638 The following command outputs partition information about the
1639 specified disk image:
1640 </para>
1641
1642<screen>$ vboximg-mount --image=f9ea7173-6869-4aa9-b487-68023a655980 --list
1643
1644 Virtual disk image:
1645
1646 Path: /Volumes/work/vm_guests/macOS High Sierra 10.13/macOS High Sierra 10.13.vdi
1647 UUID: f9ea7173-6869-4aa9-b487-68023a655980
1648
1649 # Start Sectors Size Offset Type
1650 1 40 409599 199.9M 20480 EFI System
1651 2 409640 67453071 32.1G 209735680 Hierarchical File System Plus (HFS+)
1652 3 67862712 1269535 107.8M 34745708544 Apple Boot (Recovery HD)</screen>
1653
1654 </sect2>
1655
1656 <sect2 id="vboximg-mount-steps">
1657
1658 <title>Mounting a Virtual Disk Image</title>
1659
1660 <para>
1661 The following steps show how to use the
1662 <command>vboximg-mount</command> command to mount a partition of
1663 a virtual disk image on the host OS.
1664 </para>
1665
1666 <orderedlist>
1667
1668 <listitem>
1669 <para>
1670 Create a mount point on the host OS. For example:
1671 </para>
1672
1673<screen>$ mkdir macos_sysdisk</screen>
1674 </listitem>
1675
1676 <listitem>
1677 <para>
1678 Show partition information about the virtual disk image.
1679 </para>
1680
1681<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> --list</screen>
1682
1683 <para>
1684 where <replaceable>uuid</replaceable> is the UUID of the
1685 disk image.
1686 </para>
1687 </listitem>
1688
1689 <listitem>
1690 <para>
1691 Use <command>vboximg-mount</command> to perform a FUSE mount
1692 of a partition on the virtual disk image. For example:
1693 </para>
1694
1695<screen>$ vboximg-mount --image=<replaceable>uuid</replaceable> -p 2 macos_sysdisk</screen>
1696
1697 <para>
1698 where <replaceable>uuid</replaceable> is the UUID for the
1699 disk image.
1700 </para>
1701
1702 <para>
1703 In this example, partition 2 is mounted on the
1704 <computeroutput>macos_sysdisk</computeroutput> mount point.
1705 The mount includes all snapshots for the disk image.
1706 </para>
1707 </listitem>
1708
1709 <listitem>
1710 <para>
1711 Use the host OS to mount the
1712 <computeroutput>vhdd</computeroutput> device node. The
1713 FUSE-mounted device node represents the virtual disk image.
1714 </para>
1715
1716<screen>$ ls macos_sysdisk
1717 macOS High Sierra 10.13.vdi vhdd
1718$ sudo mount macos_sysdisk/vhdd /mnt</screen>
1719 </listitem>
1720
1721 </orderedlist>
1722
1723 </sect2>
1724
1725 </sect1>
1726
1727</chapter>
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette