1.\" Copyright (c) 2013, 2014 Juniper Networks, Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd August 7, 2015 28.Dt MKIMG 1 29.Os 30.Sh NAME 31.Nm mkimg 32.Nd "utility to make disk images" 33.Sh SYNOPSIS 34.Nm 35.Op Fl H Ar heads 36.Op Fl P Ar blksz 37.Op Fl S Ar secsz 38.Op Fl T Ar tracksz 39.Op Fl b Ar bootcode 40.Op Fl c Ar capacity 41.Op Fl f Ar format 42.Op Fl o Ar outfile 43.Op Fl v 44.Op Fl y 45.Op Fl s Ar scheme Op Fl p Ar partition ... 46.Nm 47.Ar --formats | --schemes | --version 48.Sh DESCRIPTION 49The 50.Nm 51utility creates a disk image from the raw partition contents specified with 52the 53.Ar partition 54argument(s) and using the partitioning scheme specified with the 55.Ar scheme 56argument. 57The disk image is written to 58.Ar stdout 59by default or the file specified with the 60.Ar outfile 61argument. 62The image file is a raw disk image by default, but the format of the 63image file can be specified with the 64.Ar format 65argument. 66.Pp 67The disk image can be made bootable by specifying the scheme-specific boot 68block contents with the 69.Ar bootcode 70argument and, 71depending on the scheme, 72with a boot partition. 73The contents of such a boot partition is provided like any other partition 74and the 75.Nm 76utility does not treat it any differently from other partitions. 77.Pp 78Some partitioning schemes need a disk geometry and for those the 79.Nm 80utility accepts the 81.Ar tracksz 82and 83.Ar heads 84arguments, specifying the number of sectors per track and the number of 85heads per cylinder (resp.) 86.Pp 87Both the logical and physical sector size can be specified and for that the 88.Nm 89utility 90accepts the 91.Ar secsz 92and 93.Ar blksz 94arguments. 95The 96.Ar secsz 97argument is used to specify the logical sector size. 98This is the sector size reported by a disk when queried for its capacity. 99Modern disks use a larger sector size internally, 100referred to as block size by the 101.Nm 102utility and this can be specified by the 103.Ar blksz 104argument. 105The 106.Nm 107utility will use the (physical) block size to determine the start of 108partitions and to round the size of the disk image. 109.Pp 110The 111.Fl c 112option can be used to specify a minimal capacity for the disk image. 113Use this option without the 114.Fl s 115and 116.Fl p 117options to create an empty disk image with the given (virtual) size. 118An empty partition table can be written to the disk when specifying a 119partitioning scheme with the 120.Fl s 121option, but without specifying any partitions. 122When the size required to for all the partitions is larger than the 123given capacity, then the disk image will be larger than the capacity 124given. 125.Pp 126The 127.Fl v 128option increases the level of output that the 129.Nm 130utility prints. 131.Pp 132The 133.Fl y 134option is used for testing purposes only and is not to be used in production. 135When present, the 136.Nm 137utility will generate predictable values for Universally Unique Identifiers 138(UUIDs) and time stamps so that consecutive runs of the 139.Nm 140utility will create images that are identical. 141.Pp 142A set of long options exist to query about the 143.Nm 144utility itself. 145Options in this set should be given by themselves because the 146.Nm 147utility exits immediately after providing the requested information. 148The version of the 149.Nm 150utility is printed when the 151.Ar --version 152option is given. 153The list of supported output formats is printed when the 154.Ar --formats 155option is given and the list of supported partitioning schemes is printed 156when the 157.Ar --schemes 158option is given. 159Both the format and scheme lists a space-separated lists for easy handling 160in scripts. 161.Pp 162For a more descriptive list of supported partitioning schemes or supported 163output format, or for a detailed description of how to specify partitions, 164run the 165.Nm 166utility without any arguments. 167This will print a usage message with all the necessary details. 168.Sh DISK FORMATS 169The 170.Nm 171utility supports a number of output file formats. 172A short description of these is given below. 173.Ss QCOW and QCOW2 174QCOW stands for "QEMU Copy On Write". 175It's a sparse file format akin to VHD and VMDK and QCOW represents the 176first version. 177QCOW2 represents version 2 of the file format. 178Version 2 is not backward compatible with version 1 and adds support for 179snapshots among other things. 180The QCOW file formats are natively supported by QEMU and Xen. 181To write QCOW, specify 182.Fl f Ar qcow 183on the command line. 184To write version 2 QCOW, specify 185.Fl f Ar qcow2 186on the command line. 187The preferred file extension is ".qcow" and ".qcow2" for QCOW and QCOW2 188(resp.), but ".qcow" is sometimes used for version 2 files as well. 189.Ss RAW file format 190This file format is a sector by sector representation of an actual disk. 191There is no extra information that describes or relates to the format 192itself. The size of the file is the size of the (virtual) disk. 193This file format is suitable for being copyied onto a disk with utilities 194like 195.Nm dd . 196To write a raw disk file, either omit the 197.Fl f 198option, or specify 199.Fl f Ar raw 200on the command line. 201The preferred file extension is one of ".img" or ".raw", but there's no 202real convention for it. 203.Ss Dynamic VHD and Fixed VHD 204Microsoft's "Virtual Hard Disk" file formats. 205The dynamic format is a sparse format akin to QCOW and VMDK. 206The fixed format is effectively a raw format with a footer appended to the 207file and as such it's often indistinguishable from the raw format. 208The fixed file format has been added to support Microsoft's Azure platform 209and due to inconsistencies in interpretation of the footer is not compatible 210with utilities like 211.Nm qemu 212when it is specifically instructed to interpreted the file as a VHD file. 213By default 214.Nm qemu 215will treat the file as a raw disk file, which mostly works fine. 216To have 217.Nm 218create a dynamic VHD file, specify 219.Fl f Ar vhd 220on the command line. 221To create a fixed VHD file for use by Azure, specify 222.Fl f Ar vhdf 223on the command line. 224The preferred file extension is ".vhd". 225.Ss VMDK 226VMware's "Virtual Machine Disk" file format. 227It's a sparse file format akin to QCOW and VHD and supported by many 228virtualization solutions. 229To create a VMDK file, specify 230.Fl f Ar vmdk 231on the command line. 232The preferred file extension is ".vmdk". 233.Pp 234Not all virtualization solutions support all file formats, but often those 235virtualization environments have utilities to convert from one format to 236another. 237Note however that conversion may require that the virtual disk size is 238changed to match the constraints of the output format and this may invalidate 239the contents of the disk image. 240For example, the GUID Partition Table (GPT) scheme has a header in the last 241sector on the disk. 242When changing the disk size, the GPT must be changed so that the last header 243is moved accordingly. 244This is typically not part of the conversion process. 245If possible, use an output format specifically for the environment in which 246the file is intended to be used. 247.Sh ENVIRONMENT 248.Bl -tag -width "TMPDIR" -compact 249.It Ev TMPDIR 250Directory to put temporary files in; default is 251.Pa /tmp . 252.El 253.Sh EXAMPLES 254To create a bootable disk image that is partitioned using the GPT scheme and 255containing a root file system that was previously created using 256.Xr makefs 257and also containing a swap partition, run the 258.Nm 259utility as follows: 260.Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \ 261-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \ 262-o gpt.img 263.Pp 264The command line given above results in a raw image file. 265This is because no output format was given. 266To create a VMDK image for example, add the 267.Fl f Ar vmdk 268argument to the 269.Nm 270utility and name the output file accordingly. 271.Pp 272A nested partitioning scheme is created by running the 273.Nm 274utility twice. 275The output of the first will be fed as the contents of a partition to the 276second. 277This can be done using a temporary file, like so: 278.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 279-p freebsd-swap::1G -o /tmp/bsd.img 280.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img 281.Pp 282Alternatively, the 283.Nm 284utility can be run in a cascaded fashion, whereby the output of the 285first is fed directly into the second. 286To do this, run the 287.Nm 288utility as follows: 289.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \ 290-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img 291.Pp 292To accommodate the need to have partitions named or numbered in a certain 293way, the 294.Nm 295utility allows for the specification of empty partitions. 296For example, to create an image that is compatible with partition layouts 297found in 298.Pa /etc/disktab , 299the 'd' partition often needs to be skipped. 300This is accomplished by inserting an unused partition after the first 2 301partition specifications. 302It is worth noting at this time that the BSD scheme will automatically 303skip the 'c' partition by virtue of it referring to the entire disk. 304To create an image that is compatible with the qp120at disk, use the 305.Nm 306utility as follows: 307.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 308-p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \ 309-o bsd.img 310.Pp 311For partitioning schemes that feature partition labels, the 312.Nm 313utility supports assigning labels to the partitions specified. 314In the following example the file system partition is labeled as 'backup': 315.Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img 316.Sh SEE ALSO 317.Xr dd 1 , 318.Xr gpart 8 , 319.Xr makefs 8 , 320.Xr mdconfig 8 , 321.Xr newfs 8 322.Sh HISTORY 323The 324.Nm 325utility first appeared in 326.Fx 10.1 . 327.Sh AUTHORS 328The 329.Nm 330utility and manpage were written by 331.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . 332