svn commit: r286417 - head/usr.bin/mkimg

[Marcel Moolenaar]

Author: marcel
Date: Fri Aug  7 17:22:37 2015
New Revision: 286417
URL: https://svnweb.freebsd.org/changeset/base/286417

Log:
  o  Fix a typo.
  o  Describe the file formats mkimg can create.

Modified:
  head/usr.bin/mkimg/mkimg.1

Modified: head/usr.bin/mkimg/mkimg.1
==============================================================================
--- head/usr.bin/mkimg/mkimg.1	Fri Aug  7 16:23:16 2015	(r286416)
+++ head/usr.bin/mkimg/mkimg.1	Fri Aug  7 17:22:37 2015	(r286417)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 22, 2015
+.Dd August 7, 2015
 .Dt MKIMG 1
 .Os
 .Sh NAME
@@ -141,7 +141,7 @@ utility will create images that are iden
 .Pp
 A set of long options exist to query about the
 .Nm
-utilty itself.
+utility itself.
 Options in this set should be given by themselves because the
 .Nm
 utility exits immediately after providing the requested information.
@@ -165,6 +165,85 @@ run the
 .Nm
 utility without any arguments.
 This will print a usage message with all the necessary details.
+.Sh DISK FORMATS
+The
+.Nm
+utility supports a number of output file formats.
+A short description of these is given below.
+.Ss QCOW and QCOW2
+QCOW stands for "QEMU Copy On Write".
+It's a sparse file format akin to VHD and VMDK and QCOW represents the
+first version.
+QCOW2 represents version 2 of the file format.
+Version 2 is not backward compatible with version 1 and adds support for
+snapshots among other things.
+The QCOW file formats are natively supported by QEMU and Xen.
+To write QCOW, specify
+.Fl f Ar qcow
+on the command line.
+To write version 2 QCOW, specify
+.Fl f Ar qcow2
+on the command line.
+The preferred file extension is ".qcow" iand ".qcow2" for QCOW and QCOW2
+(resp.), but ".qcow" is sometimes used for version 2 files as well.
+.Ss RAW file format
+This file format is a sector by sector representation of an actual disk.
+There is no extra information that describes or relates to the format
+itself. The size of the file is the size of the (virtual) disk.
+This file format is suitable for being copyied onto a disk with utilities
+like
+.Nm dd .
+To write a raw disk file, either omit the
+.Fl f
+option, or specify
+.Fl f Ar raw
+on the command line.
+The preferred file extension is one of ".img" or ".raw", but there's no
+real convention for it.
+.Ss Dynamic VHD and Fixed VHD
+Microsoft's "Virtual Hard Disk" file formats.
+The dynamic format is a sparse format akin to QCOW and VMDK.
+The fixed format is effectively a raw format with a footer appended to the
+file and as such it's often indistinguishable from the raw format.
+The fixed file format has been added to support Microsoft's Azure platform
+and due to inconsistencies in interpretation of the footer is not compatible
+with utilities like
+.Nm qemu
+when it is specifically instructed to interpreted the file as a VHD file.
+By default
+.Nm qemu
+will treat the file as a raw disk file, which mostly works fine.
+To have
+.Nm
+create a dynamic VHD file, specify
+.Fl f Ar vhd
+on the command line.
+To create a fixed VHD file for use by Azure, specify
+.Fl f Ar vhdf
+on the command line.
+The preferred file extension is ".vhd".
+.Ss VMDK
+VMware's "Virtual Machine Disk" file format.
+It's a sparse file format akin to QCOW and VHD and supported by many
+virtualization solutions.
+To create a VMDK file, specify
+.Fl f Ar vmdk
+on the command line.
+The preferred file extension is ".vmdk".
+.Pp
+Not all virtualization solutions support all file formats, but often those
+virtualization environments have utilities to convert from one format to
+another.
+Note however that conversion may require that the virtual disk size is
+changed to match the constraints of the output format and this may invalidate
+the contents of the disk image.
+For example, the GUID Partition Table (GPT) scheme has a header in the last
+sector on the disk.
+When changing the disk size, the GPT must be changed so that the last header
+is moved accordingly.
+This is typically not part of the conversion process.
+If possible, use an output format specifically for the environment in which
+the file is intended to be used.
 .Sh ENVIRONMENT
 .Bl -tag -width "TMPDIR" -compact
 .It Ev TMPDIR
@@ -235,6 +314,7 @@ utility supports assigning labels to the
 In the following example the file system partition is labeled as 'backup':
 .Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img
 .Sh SEE ALSO
+.Xr dd 1 ,
 .Xr gpart 8 ,
 .Xr makefs 8 ,
 .Xr mdconfig 8 ,