d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
3bc8a689c1
freebsd-skq/usr.bin/mkimg/mkimg.1

236 lines
7.0 KiB
Groff
Raw Normal View History

Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.\" Copyright (c) 2013, 2014 Juniper Networks, Inc.
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.\" 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$
.\"
Update the usage message and the man page to account for the new long options. Bump the version number to 20140927. While here, use explicit fputc() calls to skip a line in the output. This to avoid having to hunt for extra '\n' characters in the printf format strings. MFC after: 1 week Relnotes: yes
2014-09-27 17:58:03 +00:00
.Dd September 27, 2014
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Dt MKIMG 1
.Os
.Sh NAME
.Nm mkimg
Document the -y option as a unit test option. Add missing -v (and -y) to the usage message. Requested by: eadler@
2014-07-04 18:47:25 +00:00
.Nd "utility to make disk images"
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Sh SYNOPSIS
.Nm
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Op Fl H Ar heads
.Op Fl P Ar blksz
.Op Fl S Ar secsz
.Op Fl T Ar tracksz
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Op Fl b Ar bootcode
Add the -f option for specifying the output format. Update the manpage accordingly. Print the scheme and the format when running verbose.
2014-05-08 01:43:33 +00:00
.Op Fl f Ar format
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Op Fl o Ar outfile
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Op Fl v
Document the -y option as a unit test option. Add missing -v (and -y) to the usage message. Requested by: eadler@
2014-07-04 18:47:25 +00:00
.Op Fl y
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Fl s Ar scheme
.Fl p Ar partition
.Op Fl p Ar partition ...
Update the usage message and the man page to account for the new long options. Bump the version number to 20140927. While here, use explicit fputc() calls to skip a line in the output. This to avoid having to hunt for extra '\n' characters in the printf format strings. MFC after: 1 week Relnotes: yes
2014-09-27 17:58:03 +00:00
.Nm
.Ar --formats | --schemes | --version
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Sh DESCRIPTION
The
.Nm
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
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.
Add the -f option for specifying the output format. Update the manpage accordingly. Print the scheme and the format when running verbose.
2014-05-08 01:43:33 +00:00
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.
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.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
.Op Fl v
option increases the level of output that the
.Nm
utility prints.
Add a paragraph about running mkimg without arguments to get a list of supported schemes and/or a detailed description of how to specify partitions.
2014-03-29 03:39:22 +00:00
.Pp
Document the -y option as a unit test option. Add missing -v (and -y) to the usage message. Requested by: eadler@
2014-07-04 18:47:25 +00:00
The
.Op 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
Update the usage message and the man page to account for the new long options. Bump the version number to 20140927. While here, use explicit fputc() calls to skip a line in the output. This to avoid having to hunt for extra '\n' characters in the printf format strings. MFC after: 1 week Relnotes: yes
2014-09-27 17:58:03 +00:00
A set of long options exist to query about the
.Nm
utilty 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
Add a paragraph about running mkimg without arguments to get a list of supported schemes and/or a detailed description of how to specify partitions.
2014-03-29 03:39:22 +00:00
.Nm
utility without any arguments.
Update the usage message and the man page to account for the new long options. Bump the version number to 20140927. While here, use explicit fputc() calls to skip a line in the output. This to avoid having to hunt for extra '\n' characters in the printf format strings. MFC after: 1 week Relnotes: yes
2014-09-27 17:58:03 +00:00
This will print a usage message with all the necessary details.
Minor mdoc improvements.
2014-06-06 19:00:43 +00:00
.Sh ENVIRONMENT
.Bl -tag -width "TMPDIR" -compact
.It Ev TMPDIR
Directory to put temporary files in; default is
.Pa /tmp .
.El
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.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
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
Mention -f vmdk and the VMDK output format in the example section.
2014-05-15 15:14:37 +00:00
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
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
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
Document how labels can be given to partitions.
2014-03-29 03:33:31 +00:00
.Pp
Add support for adding empty partition entries. I.e. skip partition numbers or names. This gives more control over the actual layout and helps to construct BSD disklabels with /usr or /var at dedicated partitions. Obtained from: Juniper Networks, Inc. MFC after: 3 days Relnotes: yes
2014-09-12 20:05:08 +00:00
To accomodate 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
Document how labels can be given to partitions.
2014-03-29 03:33:31 +00:00
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
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Sh SEE ALSO
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Xr gpart 8
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Xr makefs 8
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Xr mdconfig 8
.Xr newfs 8
Safe WIP: mkimg is a user-space utility for creating disk images. In its current form and shape, it creates images with the correct partition contents and overall image layout. What it doesn't do yet is actually scribble the metadata, such as partition tables and boot code. This is where I'd like to leverage code from other places, such as geom_part, and if possible/feasible. Also, the utility should be a little bit smarter about files and pipes so that we create temporary files only when needed (e.g. when we don't know the size of a partition's contents in advance while wrting the image to stdout).
2013-08-04 02:37:05 +00:00
.Sh HISTORY
The
.Nm
Prepare for merging to stable/10: update the history section.
2014-07-02 04:06:06 +00:00
utility first appeared in
Add a ful stop after FreeBSD's version in the history section. Pointed out by: brueffer@ (thanks!)
2014-07-02 14:34:01 +00:00
.Fx 10.1 .
Flesh-out manpage.
2014-03-28 04:43:36 +00:00
.Sh AUTHORS
The
.Nm
utility and manpage were written by Marcel Moolenaar <marcelm@juniper.net>
Reference in New Issue Copy Permalink