usr.bin/mkimg/mkimg.1

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