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