1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
|
.\" Copyright (c) 2013, 2014 Juniper Networks, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd June 8, 2020
.Dt MKIMG 1
.Os
.Sh NAME
.Nm mkimg
.Nd "utility to make disk images"
.Sh SYNOPSIS
.Nm
.Op Fl H Ar heads
.Op Fl P Ar blksz
.Op Fl S Ar secsz
.Op Fl T Ar tracksz
.Op Fl b Ar bootcode
.Op Fl c Ar min_capacity
.Op Fl C Ar max_capacity
.Op Fl -capacity Ar capacity
.Op Fl f Ar format
.Op Fl o Ar outfile
.Op Fl a Ar active
.Op Fl v
.Op Fl y
.Op Fl s Ar scheme Op Fl p Ar partition ...
.Nm
.Fl -formats | Fl -schemes | Fl -version
.Sh DESCRIPTION
The
.Nm
utility creates a disk image from the raw partition contents specified with
the
.Ar partition
argument(s) and using the partitioning scheme specified with the
.Ar scheme
argument.
The disk image is written to
.Ar stdout
by default or the file specified with the
.Ar outfile
argument.
The image file is a raw disk image by default, but the format of the
image file can be specified with the
.Ar format
argument.
.Pp
The disk image can be made bootable by specifying the scheme-specific boot
block contents with the
.Ar bootcode
argument and,
depending on the scheme,
with a boot partition.
The contents of such a boot partition is provided like any other partition
and the
.Nm
utility does not treat it any differently from other partitions.
.Pp
Some partitioning schemes need a disk geometry and for those the
.Nm
utility accepts the
.Ar tracksz
and
.Ar heads
arguments, specifying the number of sectors per track and the number of
heads per cylinder (resp.)
.Pp
Both the logical and physical sector size can be specified and for that the
.Nm
utility
accepts the
.Ar secsz
and
.Ar blksz
arguments.
The
.Ar secsz
argument is used to specify the logical sector size.
This is the sector size reported by a disk when queried for its capacity.
Modern disks use a larger sector size internally,
referred to as block size by the
.Nm
utility and this can be specified by the
.Ar blksz
argument.
The
.Nm
utility will use the (physical) block size to determine the start of
partitions and to round the size of the disk image.
.Pp
The
.Fl c
option can be used to specify a minimal capacity for the disk image.
Use this option without the
.Fl s
and
.Fl p
options to create an empty disk image with the given (virtual) size.
An empty partition table can be written to the disk when specifying a
partitioning scheme with the
.Fl s
option, but without specifying any partitions.
When the size required for all the partitions is larger than the
given capacity, then the disk image will be larger than the capacity
given.
.Pp
The
.Fl C
option specifies a maximum capacity for the disk image.
If the combined sizes of the given partitions exceed the size given with
.Fl C ,
image creation fails.
.Pp
The
.Fl -capacity
option is a shorthand to specify the minimum and maximum capacity at the
same time.
.Pp
The
.Fl v
option increases the level of output that the
.Nm
utility prints.
.Pp
The
.Fl y
option is used for testing purposes only and is not to be used in production.
When present, the
.Nm
utility will generate predictable values for Universally Unique Identifiers
(UUIDs) and time stamps so that consecutive runs of the
.Nm
utility will create images that are identical.
.Pp
The
.Ar active
option marks a partition as active, if the partitioning
scheme supports it.
Currently, only the
.Ar mbr
scheme supports this concept.
By default,
.Nm
will only mark the first partition as active when boot code is
specified.
Use the
.Ar active
option to override the active partition.
The number specified corresponds to the number after the 's' in the
partition's
.Xr geom 8
name.
No partitions are marked active when the value is 0.
.Pp
A set of long options exist to query about the
.Nm
utility itself.
Options in this set should be given by themselves because the
.Nm
utility exits immediately after providing the requested information.
The version of the
.Nm
utility is printed when the
.Fl -version
option is given.
The list of supported output formats is printed when the
.Fl -formats
option is given and the list of supported partitioning schemes is printed
when the
.Fl -schemes
option is given.
Both the format and scheme lists a space-separated lists for easy handling
in scripts.
.Pp
For a more descriptive list of supported partitioning schemes or supported
output format, or for a detailed description of how to specify partitions,
run the
.Nm
utility without any arguments.
This will print a usage message with all the necessary details.
.Sh DISK FORMATS
The
.Nm
utility supports a number of output file formats.
A short description of these is given below.
.Ss QCOW and QCOW2
QCOW stands for "QEMU Copy On Write".
It's a sparse file format akin to VHD and VMDK and QCOW represents the
first version.
QCOW2 represents version 2 of the file format.
Version 2 is not backward compatible with version 1 and adds support for
snapshots among other things.
The QCOW file formats are natively supported by QEMU and Xen.
To write QCOW, specify
.Fl f Ar qcow
on the command line.
To write version 2 QCOW, specify
.Fl f Ar qcow2
on the command line.
The preferred file extension is ".qcow" and ".qcow2" for QCOW and QCOW2
(resp.), but ".qcow" is sometimes used for version 2 files as well.
.Ss RAW file format
This file format is a sector by sector representation of an actual disk.
There is no extra information that describes or relates to the format itself.
The size of the file is the size of the (virtual) disk.
This file format is suitable for being copyied onto a disk with utilities
like
.Nm dd .
To write a raw disk file, either omit the
.Fl f
option, or specify
.Fl f Ar raw
on the command line.
The preferred file extension is one of ".img" or ".raw", but there's no
real convention for it.
.Ss Dynamic VHD and Fixed VHD
Microsoft's "Virtual Hard Disk" file formats.
The dynamic format is a sparse format akin to QCOW and VMDK.
The fixed format is effectively a raw format with a footer appended to the
file and as such it's often indistinguishable from the raw format.
The fixed file format has been added to support Microsoft's Azure platform
and due to inconsistencies in interpretation of the footer is not compatible
with utilities like
.Nm qemu
when it is specifically instructed to interpreted the file as a VHD file.
By default
.Nm qemu
will treat the file as a raw disk file, which mostly works fine.
To have
.Nm
create a dynamic VHD file, specify
.Fl f Ar vhd
on the command line.
To create a fixed VHD file for use by Azure, specify
.Fl f Ar vhdf
on the command line.
The preferred file extension is ".vhd".
.Ss Dynamic VHDX
Microsoft's "Virtual Hard Disk v2" file formats, the
successor to VHD.
VHDX is the required format for the 2nd generation Hyper-V VMs.
To have
.Nm
create a dynamic VHDX file, specify
.Fl f Ar vhdx
on the command line.
The preferred file extension is ".vhdx".
.Ss VMDK
VMware's "Virtual Machine Disk" file format.
It's a sparse file format akin to QCOW and VHD and supported by many
virtualization solutions.
To create a VMDK file, specify
.Fl f Ar vmdk
on the command line.
The preferred file extension is ".vmdk".
.Pp
Not all virtualization solutions support all file formats, but often those
virtualization environments have utilities to convert from one format to
another.
Note however that conversion may require that the virtual disk size is
changed to match the constraints of the output format and this may invalidate
the contents of the disk image.
For example, the GUID Partition Table (GPT) scheme has a header in the last
sector on the disk.
When changing the disk size, the GPT must be changed so that the last header
is moved accordingly.
This is typically not part of the conversion process.
If possible, use an output format specifically for the environment in which
the file is intended to be used.
.Sh ENVIRONMENT
.Bl -tag -width "TMPDIR" -compact
.It Ev TMPDIR
Directory to put temporary files in; default is
.Pa /tmp .
.El
.Sh EXAMPLES
To create a bootable disk image that is partitioned using the GPT scheme and
containing a root file system that was previously created using
.Xr makefs 8
and also containing a swap partition, run the
.Nm
utility as follows:
.Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \
-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \
-o gpt.img
.Pp
The command line given above results in a raw image file.
This is because no output format was given.
To create a VMDK image for example, add the
.Fl f Ar vmdk
argument to the
.Nm
utility and name the output file accordingly.
.Pp
A nested partitioning scheme is created by running the
.Nm
utility twice.
The output of the first will be fed as the contents of a partition to the
second.
This can be done using a temporary file, like so:
.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
-p freebsd-swap::1G -o /tmp/bsd.img
.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img
.Pp
Alternatively, the
.Nm
utility can be run in a cascaded fashion, whereby the output of the
first is fed directly into the second.
To do this, run the
.Nm
utility as follows:
.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \
-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img
.Pp
To accommodate the need to have partitions named or numbered in a certain
way, the
.Nm
utility allows for the specification of empty partitions.
For example, to create an image that is compatible with partition layouts
found in
.Pa /etc/disktab ,
the 'd' partition often needs to be skipped.
This is accomplished by inserting an unused partition after the first 2
partition specifications.
It is worth noting at this time that the BSD scheme will automatically
skip the 'c' partition by virtue of it referring to the entire disk.
To create an image that is compatible with the qp120at disk, use the
.Nm
utility as follows:
.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
-p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \
-o bsd.img
.Pp
For partitioning schemes that feature partition labels, the
.Nm
utility supports assigning labels to the partitions specified.
In the following example the file system partition is labeled as 'backup':
.Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img
.Sh SEE ALSO
.Xr dd 1 ,
.Xr gpart 8 ,
.Xr makefs 8 ,
.Xr mdconfig 8 ,
.Xr newfs 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 10.1 .
.Sh AUTHORS
The
.Nm
utility and manpage were written by
.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org .
|