1 .\" Copyright (c) 2013, 2014 Juniper Networks, Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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.
32 .Nd "utility to make disk images"
40 .Op Fl c Ar min_capacity
41 .Op Fl C Ar max_capacity
42 .Op Fl -capacity Ar capacity
48 .Op Fl s Ar scheme Op Fl p Ar partition ...
50 .Fl -formats | Fl -schemes | Fl -version
54 utility creates a disk image from the raw partition contents specified with
57 argument(s) and using the partitioning scheme specified with the
60 The disk image is written to
62 by default or the file specified with the
65 The image file is a raw disk image by default, but the format of the
66 image file can be specified with the
70 The disk image can be made bootable by specifying the scheme-specific boot
71 block contents with the
74 depending on the scheme,
75 with a boot partition.
76 The contents of such a boot partition is provided like any other partition
79 utility does not treat it any differently from other partitions.
81 Some partitioning schemes need a disk geometry and for those the
87 arguments, specifying the number of sectors per track and the number of
88 heads per cylinder (resp.)
90 Both the logical and physical sector size can be specified and for that the
100 argument is used to specify the logical sector size.
101 This is the sector size reported by a disk when queried for its capacity.
102 Modern disks use a larger sector size internally,
103 referred to as block size by the
105 utility and this can be specified by the
110 utility will use the (physical) block size to determine the start of
111 partitions and to round the size of the disk image.
115 option can be used to specify a minimal capacity for the disk image.
116 Use this option without the
120 options to create an empty disk image with the given (virtual) size.
121 An empty partition table can be written to the disk when specifying a
122 partitioning scheme with the
124 option, but without specifying any partitions.
125 When the size required for all the partitions is larger than the
126 given capacity, then the disk image will be larger than the capacity
131 option specifies a maximum capacity for the disk image.
132 If the combined sizes of the given partitions exceed the size given with
134 image creation fails.
138 option is a shorthand to specify the minimum and maximum capacity at the
143 option increases the level of output that the
149 option is used for testing purposes only and is not to be used in production.
152 utility will generate predictable values for Universally Unique Identifiers
153 (UUIDs) and time stamps so that consecutive runs of the
155 utility will create images that are identical.
159 option marks a partition as active, if the partitioning
163 scheme supports this concept.
166 will only mark the first partition as active when boot code is
170 option to override the active partition.
171 The number specified corresponds to the number after the 's' in the
175 No partitions are marked active when the value is 0.
177 A set of long options exist to query about the
180 Options in this set should be given by themselves because the
182 utility exits immediately after providing the requested information.
185 utility is printed when the
188 The list of supported output formats is printed when the
190 option is given and the list of supported partitioning schemes is printed
194 Both the format and scheme lists a space-separated lists for easy handling
197 For a more descriptive list of supported partitioning schemes or supported
198 output format, or for a detailed description of how to specify partitions,
201 utility without any arguments.
202 This will print a usage message with all the necessary details.
206 utility supports a number of output file formats.
207 A short description of these is given below.
209 QCOW stands for "QEMU Copy On Write".
210 It's a sparse file format akin to VHD and VMDK and QCOW represents the
212 QCOW2 represents version 2 of the file format.
213 Version 2 is not backward compatible with version 1 and adds support for
214 snapshots among other things.
215 The QCOW file formats are natively supported by QEMU and Xen.
216 To write QCOW, specify
219 To write version 2 QCOW, specify
222 The preferred file extension is ".qcow" and ".qcow2" for QCOW and QCOW2
223 (resp.), but ".qcow" is sometimes used for version 2 files as well.
225 This file format is a sector by sector representation of an actual disk.
226 There is no extra information that describes or relates to the format itself.
227 The size of the file is the size of the (virtual) disk.
228 This file format is suitable for being copyied onto a disk with utilities
231 To write a raw disk file, either omit the
236 The preferred file extension is one of ".img" or ".raw", but there's no
237 real convention for it.
238 .Ss Dynamic VHD and Fixed VHD
239 Microsoft's "Virtual Hard Disk" file formats.
240 The dynamic format is a sparse format akin to QCOW and VMDK.
241 The fixed format is effectively a raw format with a footer appended to the
242 file and as such it's often indistinguishable from the raw format.
243 The fixed file format has been added to support Microsoft's Azure platform
244 and due to inconsistencies in interpretation of the footer is not compatible
247 when it is specifically instructed to interpreted the file as a VHD file.
250 will treat the file as a raw disk file, which mostly works fine.
253 create a dynamic VHD file, specify
256 To create a fixed VHD file for use by Azure, specify
259 The preferred file extension is ".vhd".
261 Microsoft's "Virtual Hard Disk v2" file formats, the
263 VHDX is the required format for the 2nd generation Hyper-V VMs.
266 create a dynamic VHDX file, specify
269 The preferred file extension is ".vhdx".
271 VMware's "Virtual Machine Disk" file format.
272 It's a sparse file format akin to QCOW and VHD and supported by many
273 virtualization solutions.
274 To create a VMDK file, specify
277 The preferred file extension is ".vmdk".
279 Not all virtualization solutions support all file formats, but often those
280 virtualization environments have utilities to convert from one format to
282 Note however that conversion may require that the virtual disk size is
283 changed to match the constraints of the output format and this may invalidate
284 the contents of the disk image.
285 For example, the GUID Partition Table (GPT) scheme has a header in the last
287 When changing the disk size, the GPT must be changed so that the last header
288 is moved accordingly.
289 This is typically not part of the conversion process.
290 If possible, use an output format specifically for the environment in which
291 the file is intended to be used.
293 .Bl -tag -width "TMPDIR" -compact
295 Directory to put temporary files in; default is
299 To create a bootable disk image that is partitioned using the GPT scheme and
300 containing a root file system that was previously created using
302 and also containing a swap partition, run the
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 \
309 The command line given above results in a raw image file.
310 This is because no output format was given.
311 To create a VMDK image for example, add the
315 utility and name the output file accordingly.
317 A nested partitioning scheme is created by running the
320 The output of the first will be fed as the contents of a partition to the
322 This 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
329 utility can be run in a cascaded fashion, whereby the output of the
330 first is fed directly into the second.
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
337 To accommodate the need to have partitions named or numbered in a certain
340 utility allows for the specification of empty partitions.
341 For example, to create an image that is compatible with partition layouts
344 the 'd' partition often needs to be skipped.
345 This is accomplished by inserting an unused partition after the first 2
346 partition specifications.
347 It is worth noting at this time that the BSD scheme will automatically
348 skip the 'c' partition by virtue of it referring to the entire disk.
349 To create an image that is compatible with the qp120at disk, use the
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 \
356 For partitioning schemes that feature partition labels, the
358 utility supports assigning labels to the partitions specified.
359 In 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
370 utility first appeared in
375 utility and manpage were written by
376 .An Marcel Moolenaar Aq Mt marcel@FreeBSD.org .