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