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 September 12, 2014 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 f Ar format 41.Op Fl o Ar outfile 42.Op Fl v 43.Op Fl y 44.Fl s Ar scheme 45.Fl p Ar partition 46.Op Fl p Ar partition ... 47.Sh DESCRIPTION 48The 49.Nm 50utility creates a disk image from the raw partition contents specified with 51the 52.Ar partition 53argument(s) and using the partitioning scheme specified with the 54.Ar scheme 55argument. 56The disk image is written to 57.Ar stdout 58by default or the file specified with the 59.Ar outfile 60argument. 61The image file is a raw disk image by default, but the format of the 62image file can be specified with the 63.Ar format 64argument. 65.Pp 66The disk image can be made bootable by specifying the scheme-specific boot 67block contents with the 68.Ar bootcode 69argument and, 70depending on the scheme, 71with a boot partition. 72The contents of such a boot partition is provided like any other partition 73and the 74.Nm 75utility does not treat it any differently from other partitions. 76.Pp 77Some partitioning schemes need a disk geometry and for those the 78.Nm 79utility accepts the 80.Ar tracksz 81and 82.Ar heads 83arguments, specifying the number of sectors per track and the number of 84heads per cylinder (resp.) 85.Pp 86Both the logical and physical sector size can be specified and for that the 87.Nm 88utility 89accepts the 90.Ar secsz 91and 92.Ar blksz 93arguments. 94The 95.Ar secsz 96argument is used to specify the logical sector size. 97This is the sector size reported by a disk when queried for its capacity. 98Modern disks use a larger sector size internally, 99referred to as block size by the 100.Nm 101utility and this can be specified by the 102.Ar blksz 103argument. 104The 105.Nm 106utility will use the (physical) block size to determine the start of 107partitions and to round the size of the disk image. 108.Pp 109The 110.Op Fl v 111option increases the level of output that the 112.Nm 113utility prints. 114.Pp 115The 116.Op Fl y 117option is used for testing purposes only and is not to be used in production. 118When present, the 119.Nm 120utility will generate predictable values for Universally Unique Identifiers 121(UUIDs) and time stamps so that consecutive runs of the 122.Nm 123utility will create images that are identical. 124.Pp 125For a complete list of supported partitioning schemes or supported output 126format, or for a detailed description of how to specify partitions, run the 127.Nm 128utility without any arguments. 129.Sh ENVIRONMENT 130.Bl -tag -width "TMPDIR" -compact 131.It Ev TMPDIR 132Directory to put temporary files in; default is 133.Pa /tmp . 134.El 135.Sh EXAMPLES 136To create a bootable disk image that is partitioned using the GPT scheme and 137containing a root file system that was previously created using 138.Xr makefs 139and also containing a swap partition, run the 140.Nm 141utility as follows: 142.Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \ 143-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \ 144-o gpt.img 145.Pp 146The command line given above results in a raw image file. 147This is because no output format was given. 148To create a VMDK image for example, add the 149.Fl f Ar vmdk 150argument to the 151.Nm 152utility and name the output file accordingly. 153.Pp 154A nested partitioning scheme is created by running the 155.Nm 156utility twice. 157The output of the first will be fed as the contents of a partition to the 158second. 159This can be done using a temporary file, like so: 160.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 161-p freebsd-swap::1G -o /tmp/bsd.img 162.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img 163.Pp 164Alternatively, the 165.Nm 166utility can be run in a cascaded fashion, whereby the output of the 167first is fed directly into the second. 168To do this, run the 169.Nm 170utility as follows: 171.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \ 172-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img 173.Pp 174To accomodate the need to have partitions named or numbered in a certain 175way, the 176.Nm 177utility allows for the specification of empty partitions. 178For example, to create an image that is compatible with partition layouts 179found in 180.Pa /etc/disktab , 181the 'd' partition often needs to be skipped. 182This is accomplished by inserting an unused partition after the first 2 183partition specifications. 184It is worth noting at this time that the BSD scheme will automatically 185skip the 'c' partition by virtue of it referring to the entire disk. 186To create an image that is compatible with the qp120at disk, use the 187.Nm 188utility as follows: 189.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \ 190-p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \ 191-o bsd.img 192.Pp 193For partitioning schemes that feature partition labels, the 194.Nm 195utility supports assigning labels to the partitions specified. 196In the following example the file system partition is labeled as 'backup': 197.Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img 198.Sh SEE ALSO 199.Xr gpart 8 200.Xr makefs 8 201.Xr mdconfig 8 202.Xr newfs 8 203.Sh HISTORY 204The 205.Nm 206utility first appeared in 207.Fx 10.1 . 208.Sh AUTHORS 209The 210.Nm 211utility and manpage were written by Marcel Moolenaar <marcelm@juniper.net> 212