Changeset 35142 in vbox for trunk/doc/manual/en_US

Timestamp:

Dec 15, 2010 4:02:58 PM (14 years ago)

Author:

vboxsync

Message:

Manual: document readonly/multiattach image modes, image resizing

Location:

trunk/doc/manual/en_US

Files:

• user_Storage.xml (modified) (4 diffs)
• user_VBoxManage.xml (modified) (2 diffs)

trunk/doc/manual/en_US/user_Storage.xml

@@ -251 +251 @@
     the image file.</para>
 
-    <para>Note that when you create an image file, its size needs to be
-    specified, which represents a fixed geometry of the virtual disk. It is
-    therefore not possible to change the size of the virtual hard disk
-    later.</para>
+    <para>Like a physical disk, a virtual disk has a size (capacity), which
+    must be specified when the image file is created. As opposed to a physical
+    disk however, VirtualBox allows you to expand an image file after
+    creation, even if it has data already; see <xref
+    linkend="vboxmanage-modifyvdi" /> for details.<footnote>
+        <para>Image resizing was added with VirtualBox 4.0.</para>
+      </footnote></para>
 
     <para>VirtualBox supports four variants of disk image files:<itemizedlist>
@@ -290 +293 @@
       </itemizedlist></para>
 
-    <para>Irrespective of the disk format, as briefly mentioned in <xref
-    linkend="gui-createvm" />, there are two options of how to create a disk
-    image: fixed-size or dynamically expanding.</para>
+    <para>Irrespective of the disk capacity and format, as briefly mentioned
+    in <xref linkend="gui-createvm" />, there are two options of how to create
+    a disk image: fixed-size or dynamically expanding.</para>
 
     <itemizedlist>
       <listitem>
         <para>If you create a <emphasis role="bold">fixed-size
-        image</emphasis> of e.g. 10 GB, an image file of roughly the same size
-        will be created on your host system. Note that the creation of a
+        image</emphasis>, 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 10G disk, you will have a 10G 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>
@@ -477 +481 @@
 
       <listitem>
-        <para>Finally, <emphasis role="bold">immutable images</emphasis> only
+        <para>Next, <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
@@ -528 +532 @@
         linkend="vboxmanage-modifyvdi" /> for details.</para>
       </listitem>
+
+      <listitem>
+        <para>An image in <emphasis role="bold">multiattach mode</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>
+      </listitem>
+
+      <listitem>
+        <para>Finally, a <emphasis role="bold">read-only image</emphasis> is
+        one that cannot be written to at all. This can only be used for DVD
+        and floppy images: for DVD images, this mode is automatically used and
+        cannot be changed, whereas the mode can be manually set for a floppy
+        image to simulate a floppy which is write-protected. It is an error to
+        enable read-only mode for a hard disk.</para>
+      </listitem>
     </orderedlist>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -1907 +1907 @@
 
     <para>With the <computeroutput>modifyhd</computeroutput> command, you can
-    change the type of an existing image between the normal, immutable and
-    write-through modes; see <xref linkend="hdimagewrites" /> for
-    details.<note>
-        <para>For compatibility with earlier versions of VirtualBox, the
-        "modifyvdi" command is also supported and mapped internally to the
-        "modifyhd" command.</para>
+    change the characteristics of a disk image after it has been
+    created:<screen>VBoxManage modifyhd         &lt;uuid&gt;|&lt;filename&gt;
+                            [--type normal|writethrough|immutable|shareable|
+                                    readonly|multiattach]
+                            [--autoreset on|off]
+                            [--compact]
+                            [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]</screen><note>
+        <para>Despite the "hd" in the subcommand name, the command works with
+        all disk images, not only hard disks. For compatibility with earlier
+        versions of VirtualBox, the "modifyvdi" command is also supported and
+        mapped internally to the "modifyhd" command.</para>
       </note></para>
 
-    <para>For immutable (differencing) hard disks only, the
-    <computeroutput>modifyhd autoreset on|off</computeroutput> command
-    determines whether the disk is automatically reset on every VM startup
-    (again, see <xref linkend="hdimagewrites" />). The default is "on".</para>
-
-    <para>In addition, the <computeroutput>modifyhd --compact</computeroutput>
-    command can be used to compact disk images, i.e. remove blocks that only
-    contains zeroes. For this operation to be effective, it is required to
-    zero out free space in the guest system using a suitable software tool.
-    Microsoft provides the <computeroutput>sdelete</computeroutput> tool for
-    Windows guests. Execute <computeroutput>sdelete -c</computeroutput> in the
-    guest to zero the free disk space before compressing the virtual disk
-    image. Compaction works both for base images and for diff images created
-    as part of a snapshot.</para>
+    <para>The following options are available:<itemizedlist>
+        <listitem>
+          <para>With the <computeroutput>--type</computeroutput> argument, you
+          can change the type of an existing image between the normal,
+          immutable, write-through and other modes; see <xref
+          linkend="hdimagewrites" /> for details.</para>
+        </listitem>
+
+        <listitem>
+          <para>For immutable (differencing) hard disks only, the
+          <computeroutput>--autoreset on|off</computeroutput> option
+          determines whether the disk is automatically reset on every VM
+          startup (again, see <xref linkend="hdimagewrites" />). The default
+          is "on".</para>
+        </listitem>
+
+        <listitem>
+          <para>With the <computeroutput>--compact</computeroutput> option,
+          can be used to compact disk images, i.e. remove blocks that only
+          contains zeroes. This will shrink a dynamically expanding image
+          again; it will reduce the <emphasis>physical</emphasis> size of the
+          image without affecting the logical size of the virtual disk.
+          Compaction works both for base images and for diff images created as
+          part of a snapshot.</para>
+
+          <para>For this operation to be effective, it is required that free
+          space in the guest system first be zeroed out using a suitable
+          software tool. For Windows guests, you can use the
+          <computeroutput>sdelete</computeroutput> tool provided by Microsoft.
+          Execute <computeroutput>sdelete -c</computeroutput> in the guest to
+          zero the free disk space before compressing the virtual disk image.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>The --resize option allows you to expand the capacity of an
+          existing image; this increases the <emphasis>logical</emphasis> size
+          of a virtual disk without affecting the physical size much.<footnote>
+              <para>Image resizing was added with VirtualBox 4.0.</para>
+            </footnote> This currently works only for the VDI and VHD formats,
+          and only for the dynamically expanding variants. For example, if you
+          originally created a 10G disk which is now full, you can use the
+          --resize command to add more space to the virtual disk without
+          having to create a new image and copy all data from within a virtual
+          machine.</para>
+        </listitem>
+      </itemizedlist></para>
   </sect1>
 
@@ -2937 +2975 @@
         <listitem>
           <para>To add a new extension pack, use <computeroutput>VBoxManage
-          extpack install &lt;tarball&gt;</computeroutput>. </para>
+          extpack install &lt;tarball&gt;</computeroutput>.</para>
         </listitem>