2dcfca637d
Add a -C option to specify a maximum capacity for the final image file. It is useful to control the size of the generated image for sdcard or when we will add dynamic size partition. Add --capacity which is a shorthand to define min and max capacity at the same time. Reviewed by: bapt, marcel, wblock (manpages) Sponsored by: Gandi.net Differential Revision: https://reviews.freebsd.org/D10509
367 lines
11 KiB
Groff
367 lines
11 KiB
Groff
.\" 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 April 26, 2017
|
|
.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
|
|
.Ar --formats | --schemes | --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
|
|
.Ar --version
|
|
option is given.
|
|
The list of supported output formats is printed when the
|
|
.Ar --formats
|
|
option is given and the list of supported partitioning schemes is printed
|
|
when the
|
|
.Ar --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 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 .
|