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