xref: /freebsd/usr.bin/mkimg/mkimg.1 (revision a0e793cbf1951d07fc47a0d9ea389d7dacba5213)
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 July 4, 2014
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 f Ar format
41.Op Fl o Ar outfile
42.Op Fl v
43.Op Fl y
44.Fl s Ar scheme
45.Fl p Ar partition
46.Op Fl p Ar partition ...
47.Sh DESCRIPTION
48The
49.Nm
50utility creates a disk image from the raw partition contents specified with
51the
52.Ar partition
53argument(s) and using the partitioning scheme specified with the
54.Ar scheme
55argument.
56The disk image is written to
57.Ar stdout
58by default or the file specified with the
59.Ar outfile
60argument.
61The image file is a raw disk image by default, but the format of the
62image file can be specified with the
63.Ar format
64argument.
65.Pp
66The disk image can be made bootable by specifying the scheme-specific boot
67block contents with the
68.Ar bootcode
69argument and,
70depending on the scheme,
71with a boot partition.
72The contents of such a boot partition is provided like any other partition
73and the
74.Nm
75utility does not treat it any differently from other partitions.
76.Pp
77Some partitioning schemes need a disk geometry and for those the
78.Nm
79utility accepts the
80.Ar tracksz
81and
82.Ar heads
83arguments, specifying the number of sectors per track and the number of
84heads per cylinder (resp.)
85.Pp
86Both the logical and physical sector size can be specified and for that the
87.Nm
88utility
89accepts the
90.Ar secsz
91and
92.Ar blksz
93arguments.
94The
95.Ar secsz
96argument is used to specify the logical sector size.
97This is the sector size reported by a disk when queried for its capacity.
98Modern disks use a larger sector size internally,
99referred to as block size by the
100.Nm
101utility and this can be specified by the
102.Ar blksz
103argument.
104The
105.Nm
106utility will use the (physical) block size to determine the start of
107partitions and to round the size of the disk image.
108.Pp
109The
110.Op Fl v
111option increases the level of output that the
112.Nm
113utility prints.
114.Pp
115The
116.Op Fl y
117option is used for testing purposes only and is not to be used in production.
118When present, the
119.Nm
120utility will generate predictable values for Universally Unique Identifiers
121(UUIDs) and time stamps so that consecutive runs of the
122.Nm
123utility will create images that are identical.
124.Pp
125For a complete list of supported partitioning schemes or supported output
126format, or for a detailed description of how to specify partitions, run the
127.Nm
128utility without any arguments.
129.Sh ENVIRONMENT
130.Bl -tag -width "TMPDIR" -compact
131.It Ev TMPDIR
132Directory to put temporary files in; default is
133.Pa /tmp .
134.El
135.Sh EXAMPLES
136To create a bootable disk image that is partitioned using the GPT scheme and
137containing a root file system that was previously created using
138.Xr makefs
139and also containing a swap partition, run the
140.Nm
141utility as follows:
142.Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \
143-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \
144-o gpt.img
145.Pp
146The command line given above results in a raw image file.
147This is because no output format was given.
148To create a VMDK image for example, add the
149.Fl f Ar vmdk
150argument to the
151.Nm
152utility and name the output file accordingly.
153.Pp
154A nested partitioning scheme is created by running the
155.Nm
156utility twice.
157The output of the first will be fed as the contents of a partition to the
158second.
159This can be done using a temporary file, like so:
160.Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
161-p freebsd-swap::1G -o /tmp/bsd.img
162.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img
163.Pp
164Alternatively, the
165.Nm
166utility can be run in a cascaded fashion, whereby the output of the
167first is fed directly into the second.
168To do this, run the
169.Nm
170utility as follows:
171.Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \
172-p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img
173.Pp
174For partitioning schemes that feature partition labels, the
175.Nm
176utility supports assigning labels to the partitions specified.
177In the following example the file system partition is labeled as 'backup':
178.Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img
179.Sh SEE ALSO
180.Xr gpart 8
181.Xr makefs 8
182.Xr mdconfig 8
183.Xr newfs 8
184.Sh HISTORY
185The
186.Nm
187utility first appeared in
188.Fx 10.1 .
189.Sh AUTHORS
190The
191.Nm
192utility and manpage were written by Marcel Moolenaar <marcelm@juniper.net>
193