Index: /trunk/doc/manual/en_US/user_Storage.xml =================================================================== --- /trunk/doc/manual/en_US/user_Storage.xml (revision 35141) +++ /trunk/doc/manual/en_US/user_Storage.xml (revision 35142) @@ -251,8 +251,11 @@ the image file. - 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. + 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 for details. + Image resizing was added with VirtualBox 4.0. + VirtualBox supports four variants of disk image files: @@ -290,13 +293,14 @@ - Irrespective of the disk format, as briefly mentioned in , there are two options of how to create a disk - image: fixed-size or dynamically expanding. + Irrespective of the disk capacity and format, as briefly mentioned + in , there are two options of how to create + a disk image: fixed-size or dynamically expanding. If you create a fixed-size - image 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, 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. @@ -477,5 +481,5 @@ - Finally, immutable images only + Next, immutable images only remember write accesses temporarily while the virtual machine is running; all changes are lost when the virtual machine is powered on @@ -528,4 +532,28 @@ linkend="vboxmanage-modifyvdi" /> for details. + + + An image in multiattach mode + 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. + + Technically, a "multiattach" image behaves identically to an + "immutable" image except the differencing image is not reset every + time the machine starts. + + + + Finally, a read-only image 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. + Index: /trunk/doc/manual/en_US/user_VBoxManage.xml =================================================================== --- /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35141) +++ /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 35142) @@ -1907,26 +1907,64 @@ With the modifyhd command, you can - change the type of an existing image between the normal, immutable and - write-through modes; see for - details. - For compatibility with earlier versions of VirtualBox, the - "modifyvdi" command is also supported and mapped internally to the - "modifyhd" command. + change the characteristics of a disk image after it has been + created:VBoxManage modifyhd <uuid>|<filename> + [--type normal|writethrough|immutable|shareable| + readonly|multiattach] + [--autoreset on|off] + [--compact] + [--resize <megabytes>|--resizebyte <bytes>] + 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. - For immutable (differencing) hard disks only, the - modifyhd autoreset on|off command - determines whether the disk is automatically reset on every VM startup - (again, see ). The default is "on". - - In addition, the modifyhd --compact - 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 sdelete tool for - Windows guests. Execute sdelete -c 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. + The following options are available: + + With the --type argument, you + can change the type of an existing image between the normal, + immutable, write-through and other modes; see for details. + + + + For immutable (differencing) hard disks only, the + --autoreset on|off option + determines whether the disk is automatically reset on every VM + startup (again, see ). The default + is "on". + + + + With the --compact 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 physical 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. + + 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 + sdelete tool provided by Microsoft. + Execute sdelete -c in the guest to + zero the free disk space before compressing the virtual disk image. + + + + + The --resize option allows you to expand the capacity of an + existing image; this increases the logical size + of a virtual disk without affecting the physical size much. + Image resizing was added with VirtualBox 4.0. + 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. + + @@ -2937,5 +2975,5 @@ To add a new extension pack, use VBoxManage - extpack install <tarball>. + extpack install <tarball>.