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 June 8, 2020 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 min_capacity 41.Op Fl C Ar max_capacity 42.Op Fl -capacity Ar capacity 43.Op Fl f Ar format 44.Op Fl o Ar outfile 45.Op Fl a Ar active 46.Op Fl v 47.Op Fl y 48.Op Fl s Ar scheme Op Fl p Ar partition ... 49.Nm 50.Fl -formats | Fl -schemes | Fl -version 51.Sh DESCRIPTION 52The 53.Nm 54utility creates a disk image from the raw partition contents specified with 55the 56.Ar partition 57argument(s) and using the partitioning scheme specified with the 58.Ar scheme 59argument. 60The disk image is written to 61.Ar stdout 62by default or the file specified with the 63.Ar outfile 64argument. 65The image file is a raw disk image by default, but the format of the 66image file can be specified with the 67.Ar format 68argument. 69.Pp 70The disk image can be made bootable by specifying the scheme-specific boot 71block contents with the 72.Ar bootcode 73argument and, 74depending on the scheme, 75with a boot partition. 76The contents of such a boot partition is provided like any other partition 77and the 78.Nm 79utility does not treat it any differently from other partitions. 80.Pp 81Some partitioning schemes need a disk geometry and for those the 82.Nm 83utility accepts the 84.Ar tracksz 85and 86.Ar heads 87arguments, specifying the number of sectors per track and the number of 88heads per cylinder (resp.) 89.Pp 90Both the logical and physical sector size can be specified and for that the 91.Nm 92utility 93accepts the 94.Ar secsz 95and 96.Ar blksz 97arguments. 98The 99.Ar secsz 100argument is used to specify the logical sector size. 101This is the sector size reported by a disk when queried for its capacity. 102Modern disks use a larger sector size internally, 103referred to as block size by the 104.Nm 105utility and this can be specified by the 106.Ar blksz 107argument. 108The 109.Nm 110utility will use the (physical) block size to determine the start of 111partitions and to round the size of the disk image. 112.Pp 113The 114.Fl c 115option can be used to specify a minimal capacity for the disk image. 116Use this option without the 117.Fl s 118and 119.Fl p 120options to create an empty disk image with the given (virtual) size. 121An empty partition table can be written to the disk when specifying a 122partitioning scheme with the 123.Fl s 124option, but without specifying any partitions. 125When the size required for all the partitions is larger than the 126given capacity, then the disk image will be larger than the capacity 127given. 128.Pp 129The 130.Fl C 131option specifies a maximum capacity for the disk image. 132If the combined sizes of the given partitions exceed the size given with 133.Fl C , 134image creation fails. 135.Pp 136The 137.Fl -capacity 138option is a shorthand to specify the minimum and maximum capacity at the 139same time. 140.Pp 141The 142.Fl v 143option increases the level of output that the 144.Nm 145utility prints. 146.Pp 147The 148.Fl y 149option is used for testing purposes only and is not to be used in production. 150When present, the 151.Nm 152utility will generate predictable values for Universally Unique Identifiers 153(UUIDs) and time stamps so that consecutive runs of the 154.Nm 155utility will create images that are identical. 156.Pp 157The 158.Ar active 159option marks a partition as active, if the partitioning 160scheme supports it. 161Currently, only the 162.Ar mbr 163scheme supports this concept. 164By default, 165.Nm 166will only mark the first partition as active when boot code is 167specified. 168Use the 169.Ar active 170option to override the active partition. 171The number specified corresponds to the number after the 's' in the 172partition's 173.Xr geom 8 174name. 175No partitions are marked active when the value is 0. 176.Pp 177A set of long options exist to query about the 178.Nm 179utility itself. 180Options in this set should be given by themselves because the 181.Nm 182utility exits immediately after providing the requested information. 183The version of the 184.Nm 185utility is printed when the 186.Fl -version 187option is given. 188The list of supported output formats is printed when the 189.Fl -formats 190option is given and the list of supported partitioning schemes is printed 191when the 192.Fl -schemes 193option is given. 194Both the format and scheme lists a space-separated lists for easy handling 195in scripts. 196.Pp 197For a more descriptive list of supported partitioning schemes or supported 198output format, or for a detailed description of how to specify partitions, 199run the 200.Nm 201utility without any arguments. 202This will print a usage message with all the necessary details. 203.Sh DISK FORMATS 204The 205.Nm 206utility supports a number of output file formats. 207A short description of these is given below. 208.Ss QCOW and QCOW2 209QCOW stands for "QEMU Copy On Write". 210It's a sparse file format akin to VHD and VMDK and QCOW represents the 211first version. 212QCOW2 represents version 2 of the file format. 213Version 2 is not backward compatible with version 1 and adds support for 214snapshots among other things. 215The QCOW file formats are natively supported by QEMU and Xen. 216To write QCOW, specify 217.Fl f Ar qcow 218on the command line. 219To write version 2 QCOW, specify 220.Fl f Ar qcow2 221on the command line. 222The preferred file extension is ".qcow" and ".qcow2" for QCOW and QCOW2 223(resp.), but ".qcow" is sometimes used for version 2 files as well. 224.Ss RAW file format 225This file format is a sector by sector representation of an actual disk. 226There is no extra information that describes or relates to the format itself. 227The size of the file is the size of the (virtual) disk. 228This file format is suitable for being copyied onto a disk with utilities 229like 230.Nm dd . 231To write a raw disk file, either omit the 232.Fl f 233option, or specify 234.Fl f Ar raw 235on the command line. 236The preferred file extension is one of ".img" or ".raw", but there's no 237real convention for it. 238.Ss Dynamic VHD and Fixed VHD 239Microsoft's "Virtual Hard Disk" file formats. 240The dynamic format is a sparse format akin to QCOW and VMDK. 241The fixed format is effectively a raw format with a footer appended to the 242file and as such it's often indistinguishable from the raw format. 243The fixed file format has been added to support Microsoft's Azure platform 244and due to inconsistencies in interpretation of the footer is not compatible 245with utilities like 246.Nm qemu 247when it is specifically instructed to interpreted the file as a VHD file. 248By default 249.Nm qemu 250will treat the file as a raw disk file, which mostly works fine. 251To have 252.Nm 253create a dynamic VHD file, specify 254.Fl f Ar vhd 255on the command line. 256To create a fixed VHD file for use by Azure, specify 257.Fl f Ar vhdf 258on the command line. 259The preferred file extension is ".vhd". 260.Ss Dynamic VHDX 261Microsoft's "Virtual Hard Disk v2" file formats, the 262successor to VHD. 263VHDX is the required format for the 2nd generation Hyper-V VMs. 264To have 265.Nm 266create a dynamic VHDX file, specify 267.Fl f Ar vhdx 268on the command line. 269The preferred file extension is ".vhdx". 270.Ss VMDK 271VMware's "Virtual Machine Disk" file format. 272It's a sparse file format akin to QCOW and VHD and supported by many 273virtualization solutions. 274To create a VMDK file, specify 275.Fl f Ar vmdk 276on the command line. 277The preferred file extension is ".vmdk". 278.Pp 279Not all virtualization solutions support all file formats, but often those 280virtualization environments have utilities to convert from one format to 281another. 282Note however that conversion may require that the virtual disk size is 283changed to match the constraints of the output format and this may invalidate 284the contents of the disk image. 285For example, the GUID Partition Table (GPT) scheme has a header in the last 286sector on the disk. 287When changing the disk size, the GPT must be changed so that the last header 288is moved accordingly. 289This is typically not part of the conversion process. 290If possible, use an output format specifically for the environment in which 291the file is intended to be used. 292.Sh ENVIRONMENT 293.Bl -tag -width "TMPDIR" -compact 294.It Ev TMPDIR 295Directory to put temporary files in; default is 296.Pa /tmp . 297.El 298.Sh EXAMPLES 299To create a bootable disk image that is partitioned using the GPT scheme and 300containing a root file system that was previously created using 301.Xr makefs 8 302and also containing a swap partition, run the 303.Nm 304utility as follows: 305.Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \ 306-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \ 307-o gpt.img 308.Pp 309The command line given above results in a raw image file. 310This is because no output format was given. 311To create a VMDK image for example, add the 312.Fl f Ar vmdk 313argument to the 314.Nm 315utility and name the output file accordingly. 316.Pp 317A nested partitioning scheme is created by running the 318.Nm 319utility twice. 320The output of the first will be fed as the contents of a partition to the 321second. 322This can be done using a temporary file, like so: 323.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 324-p freebsd-swap::1G -o /tmp/bsd.img 325.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img 326.Pp 327Alternatively, the 328.Nm 329utility can be run in a cascaded fashion, whereby the output of the 330first is fed directly into the second. 331To do this, run the 332.Nm 333utility as follows: 334.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \ 335-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img 336.Pp 337To accommodate the need to have partitions named or numbered in a certain 338way, the 339.Nm 340utility allows for the specification of empty partitions. 341For example, to create an image that is compatible with partition layouts 342found in 343.Pa /etc/disktab , 344the 'd' partition often needs to be skipped. 345This is accomplished by inserting an unused partition after the first 2 346partition specifications. 347It is worth noting at this time that the BSD scheme will automatically 348skip the 'c' partition by virtue of it referring to the entire disk. 349To create an image that is compatible with the qp120at disk, use the 350.Nm 351utility as follows: 352.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 353-p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \ 354-o bsd.img 355.Pp 356For partitioning schemes that feature partition labels, the 357.Nm 358utility supports assigning labels to the partitions specified. 359In the following example the file system partition is labeled as 'backup': 360.Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img 361.Sh SEE ALSO 362.Xr dd 1 , 363.Xr gpart 8 , 364.Xr makefs 8 , 365.Xr mdconfig 8 , 366.Xr newfs 8 367.Sh HISTORY 368The 369.Nm 370utility first appeared in 371.Fx 10.1 . 372.Sh AUTHORS 373The 374.Nm 375utility and manpage were written by 376.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org . 377