xref: /freebsd/usr.bin/mkimg/mkimg.1 (revision 076ad2f836d5f49dc1375f1677335a48fe0d4b82)
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
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.Fl c
113option can be used to specify a minimal capacity for the disk image.
114Use this option without the
115.Fl s
116and
117.Fl p
118options to create an empty disk image with the given (virtual) size.
119An empty partition table can be written to the disk when specifying a
120partitioning scheme with the
121.Fl s
122option, but without specifying any partitions.
123When the size required for all the partitions is larger than the
124given capacity, then the disk image will be larger than the capacity
125given.
126.Pp
127The
128.Fl v
129option increases the level of output that the
130.Nm
131utility prints.
132.Pp
133The
134.Fl y
135option is used for testing purposes only and is not to be used in production.
136When present, the
137.Nm
138utility will generate predictable values for Universally Unique Identifiers
139(UUIDs) and time stamps so that consecutive runs of the
140.Nm
141utility will create images that are identical.
142.Pp
143The
144.Ar active
145option marks a partition as active, if the partitioning
146scheme supports it.
147Currently, only the
148.Ar mbr
149scheme supports this concept.
150By default,
151.Nm
152will only mark the first partition as active when boot code is
153specified.
154Use the
155.Ar active
156option to override the active partition.
157The number specified corresponds to the number after the 's' in the
158partition's
159.Xr geom 8
160name.
161No partitions are marked active when the value is 0.
162.Pp
163A set of long options exist to query about the
164.Nm
165utility itself.
166Options in this set should be given by themselves because the
167.Nm
168utility exits immediately after providing the requested information.
169The version of the
170.Nm
171utility is printed when the
172.Ar --version
173option is given.
174The list of supported output formats is printed when the
175.Ar --formats
176option is given and the list of supported partitioning schemes is printed
177when the
178.Ar --schemes
179option is given.
180Both the format and scheme lists a space-separated lists for easy handling
181in scripts.
182.Pp
183For a more descriptive list of supported partitioning schemes or supported
184output format, or for a detailed description of how to specify partitions,
185run the
186.Nm
187utility without any arguments.
188This will print a usage message with all the necessary details.
189.Sh DISK FORMATS
190The
191.Nm
192utility supports a number of output file formats.
193A short description of these is given below.
194.Ss QCOW and QCOW2
195QCOW stands for "QEMU Copy On Write".
196It's a sparse file format akin to VHD and VMDK and QCOW represents the
197first version.
198QCOW2 represents version 2 of the file format.
199Version 2 is not backward compatible with version 1 and adds support for
200snapshots among other things.
201The QCOW file formats are natively supported by QEMU and Xen.
202To write QCOW, specify
203.Fl f Ar qcow
204on the command line.
205To write version 2 QCOW, specify
206.Fl f Ar qcow2
207on the command line.
208The 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
211This file format is a sector by sector representation of an actual disk.
212There is no extra information that describes or relates to the format
213itself. The size of the file is the size of the (virtual) disk.
214This file format is suitable for being copyied onto a disk with utilities
215like
216.Nm dd .
217To write a raw disk file, either omit the
218.Fl f
219option, or specify
220.Fl f Ar raw
221on the command line.
222The preferred file extension is one of ".img" or ".raw", but there's no
223real convention for it.
224.Ss Dynamic VHD and Fixed VHD
225Microsoft's "Virtual Hard Disk" file formats.
226The dynamic format is a sparse format akin to QCOW and VMDK.
227The fixed format is effectively a raw format with a footer appended to the
228file and as such it's often indistinguishable from the raw format.
229The fixed file format has been added to support Microsoft's Azure platform
230and due to inconsistencies in interpretation of the footer is not compatible
231with utilities like
232.Nm qemu
233when it is specifically instructed to interpreted the file as a VHD file.
234By default
235.Nm qemu
236will treat the file as a raw disk file, which mostly works fine.
237To have
238.Nm
239create a dynamic VHD file, specify
240.Fl f Ar vhd
241on the command line.
242To create a fixed VHD file for use by Azure, specify
243.Fl f Ar vhdf
244on the command line.
245The preferred file extension is ".vhd".
246.Ss VMDK
247VMware's "Virtual Machine Disk" file format.
248It's a sparse file format akin to QCOW and VHD and supported by many
249virtualization solutions.
250To create a VMDK file, specify
251.Fl f Ar vmdk
252on the command line.
253The preferred file extension is ".vmdk".
254.Pp
255Not all virtualization solutions support all file formats, but often those
256virtualization environments have utilities to convert from one format to
257another.
258Note however that conversion may require that the virtual disk size is
259changed to match the constraints of the output format and this may invalidate
260the contents of the disk image.
261For example, the GUID Partition Table (GPT) scheme has a header in the last
262sector on the disk.
263When changing the disk size, the GPT must be changed so that the last header
264is moved accordingly.
265This is typically not part of the conversion process.
266If possible, use an output format specifically for the environment in which
267the file is intended to be used.
268.Sh ENVIRONMENT
269.Bl -tag -width "TMPDIR" -compact
270.It Ev TMPDIR
271Directory to put temporary files in; default is
272.Pa /tmp .
273.El
274.Sh EXAMPLES
275To create a bootable disk image that is partitioned using the GPT scheme and
276containing a root file system that was previously created using
277.Xr makefs 8
278and also containing a swap partition, run the
279.Nm
280utility 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
285The command line given above results in a raw image file.
286This is because no output format was given.
287To create a VMDK image for example, add the
288.Fl f Ar vmdk
289argument to the
290.Nm
291utility and name the output file accordingly.
292.Pp
293A nested partitioning scheme is created by running the
294.Nm
295utility twice.
296The output of the first will be fed as the contents of a partition to the
297second.
298This 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
303Alternatively, the
304.Nm
305utility can be run in a cascaded fashion, whereby the output of the
306first is fed directly into the second.
307To do this, run the
308.Nm
309utility 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
313To accommodate the need to have partitions named or numbered in a certain
314way, the
315.Nm
316utility allows for the specification of empty partitions.
317For example, to create an image that is compatible with partition layouts
318found in
319.Pa /etc/disktab ,
320the 'd' partition often needs to be skipped.
321This is accomplished by inserting an unused partition after the first 2
322partition specifications.
323It is worth noting at this time that the BSD scheme will automatically
324skip the 'c' partition by virtue of it referring to the entire disk.
325To create an image that is compatible with the qp120at disk, use the
326.Nm
327utility 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
332For partitioning schemes that feature partition labels, the
333.Nm
334utility supports assigning labels to the partitions specified.
335In 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
344The
345.Nm
346utility first appeared in
347.Fx 10.1 .
348.Sh AUTHORS
349The
350.Nm
351utility and manpage were written by
352.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org .
353