diff options
Diffstat (limited to 'static/freebsd/man1/mkimg.1')
| -rw-r--r-- | static/freebsd/man1/mkimg.1 | 432 |
1 files changed, 432 insertions, 0 deletions
diff --git a/static/freebsd/man1/mkimg.1 b/static/freebsd/man1/mkimg.1 new file mode 100644 index 00000000..d3e6285d --- /dev/null +++ b/static/freebsd/man1/mkimg.1 @@ -0,0 +1,432 @@ +.\" 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. +.\" +.Dd December 30, 2025 +.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 h +.Op Fl o Ar outfile +.Op Fl a Ar active +.Op Fl t Ar timestamp +.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. +Most formats require seekable output, except of raw disk image. +.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 t +option causes any timestamps embedded in the output file to be set to the +given time, specified in seconds since the epoch. +.Pp +The +.Fl h +option prints a usage message and exits. +.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 copied 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 PARTITION SPECIFICATION +An option +.Fl p +may be used multiple times to specify a list of created partition entries. +A specification that is a single dash indicates an unused partition entry. +Otherwise, a partition specification has the following format: +.Bd -literal -offset indent +<type>[/<label>]::<size>[:[+]<offset>] +<type>[/<label>]:=<file>[:[+]<offset>] +<type>[/<label>]:-<cmd> +- +.Ed +.Bl -tag -width indent +.It Cm type +the partition type alias (f.e.: freebsd-swap) +(see the +.Sx EXAMPLES +Section below) +.It Cm label +an optional label for partitioning schemes that support labels +.It Cm size +the size of an empty partition, a number that may be suffixed with one of +K, M, G, T, P or E (either upper or lower case) following the SI power of +two convention (see also +.Xr expand_number 3 ) +.It Cm file +the name of a file to read; the partition size is determined by the file +.It Cm cmd +a command to run; the output of which is the contents of the partition. +Multi-word strings should be quoted according to the shell rules. +.It Cm offset +an optional byte offset for the +.Cm size +and +.Cm file +forms. +If prefixed with +.Ql + , +it is relative to the end of the previous partition; otherwise it is an +absolute offset from the start of the image. +The value follows the same numeric conventions as +.Cm size . +.It Cm - +an unused partition entry. +.El +.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 expand_number 3 , +.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 . |