usr.bin/mkimg/mkimg.1

   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 September 27, 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 .Nm
  48 .Ar --formats | --schemes | --version
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility creates a disk image from the raw partition contents specified with
  53 the
  54 .Ar partition
  55 argument(s) and using the partitioning scheme specified with the
  56 .Ar scheme
  57 argument.
  58 The disk image is written to
  59 .Ar stdout
  60 by default or the file specified with the
  61 .Ar outfile
  62 argument.
  63 The image file is a raw disk image by default, but the format of the
  64 image file can be specified with the
  65 .Ar format
  66 argument.
  67 .Pp
  68 The disk image can be made bootable by specifying the scheme-specific boot
  69 block contents with the
  70 .Ar bootcode
  71 argument and,
  72 depending on the scheme,
  73 with a boot partition.
  74 The contents of such a boot partition is provided like any other partition
  75 and the
  76 .Nm
  77 utility does not treat it any differently from other partitions.
  78 .Pp
  79 Some partitioning schemes need a disk geometry and for those the
  80 .Nm
  81 utility accepts the
  82 .Ar tracksz
  83 and
  84 .Ar heads
  85 arguments, specifying the number of sectors per track and the number of
  86 heads per cylinder (resp.)
  87 .Pp
  88 Both the logical and physical sector size can be specified and for that the
  89 .Nm
  90 utility
  91 accepts the
  92 .Ar secsz
  93 and
  94 .Ar blksz
  95 arguments.
  96 The
  97 .Ar secsz
  98 argument is used to specify the logical sector size.
  99 This is the sector size reported by a disk when queried for its capacity.
 100 Modern disks use a larger sector size internally,
 101 referred to as block size by the
 102 .Nm
 103 utility and this can be specified by the
 104 .Ar blksz
 105 argument.
 106 The
 107 .Nm
 108 utility will use the (physical) block size to determine the start of
 109 partitions and to round the size of the disk image.
 110 .Pp
 111 The
 112 .Op Fl v
 113 option increases the level of output that the
 114 .Nm
 115 utility prints.
 116 .Pp
 117 The
 118 .Op Fl y
 119 option is used for testing purposes only and is not to be used in production.
 120 When present, the
 121 .Nm
 122 utility will generate predictable values for Universally Unique Identifiers
 123 (UUIDs) and time stamps so that consecutive runs of the
 124 .Nm
 125 utility will create images that are identical.
 126 .Pp
 127 A set of long options exist to query about the
 128 .Nm
 129 utilty itself.
 130 Options in this set should be given by themselves because the
 131 .Nm
 132 utility exits immediately after providing the requested information.
 133 The version of the
 134 .Nm
 135 utility is printed when the
 136 .Ar --version
 137 option is given.
 138 The list of supported output formats is printed when the
 139 .Ar --formats
 140 option is given and the list of supported partitioning schemes is printed
 141 when the
 142 .Ar --schemes
 143 option is given.
 144 Both the format and scheme lists a space-separated lists for easy handling
 145 in scripts.
 146 .Pp
 147 For a more descriptive list of supported partitioning schemes or supported
 148 output format, or for a detailed description of how to specify partitions,
 149 run the
 150 .Nm
 151 utility without any arguments.
 152 This will print a usage message with all the necessary details.
 153 .Sh ENVIRONMENT
 154 .Bl -tag -width "TMPDIR" -compact
 155 .It Ev TMPDIR
 156 Directory to put temporary files in; default is
 157 .Pa /tmp .
 158 .El
 159 .Sh EXAMPLES
 160 To create a bootable disk image that is partitioned using the GPT scheme and
 161 containing a root file system that was previously created using
 162 .Xr makefs
 163 and also containing a swap partition, run the
 164 .Nm
 165 utility as follows:
 166 .Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \
 167 -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \
 168 -o gpt.img
 169 .Pp
 170 The command line given above results in a raw image file.
 171 This is because no output format was given.
 172 To create a VMDK image for example, add the
 173 .Fl f Ar vmdk
 174 argument to the
 175 .Nm
 176 utility and name the output file accordingly.
 177 .Pp
 178 A nested partitioning scheme is created by running the
 179 .Nm
 180 utility twice.
 181 The output of the first will be fed as the contents of a partition to the
 182 second.
 183 This can be done using a temporary file, like so:
 184 .Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
 185 -p freebsd-swap::1G -o /tmp/bsd.img
 186 .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img
 187 .Pp
 188 Alternatively, the
 189 .Nm
 190 utility can be run in a cascaded fashion, whereby the output of the
 191 first is fed directly into the second.
 192 To do this, run the
 193 .Nm
 194 utility as follows:
 195 .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \
 196 -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img
 197 .Pp
 198 To accomodate the need to have partitions named or numbered in a certain
 199 way, the
 200 .Nm
 201 utility allows for the specification of empty partitions.
 202 For example, to create an image that is compatible with partition layouts
 203 found in
 204 .Pa /etc/disktab ,
 205 the 'd' partition often needs to be skipped.
 206 This is accomplished by inserting an unused partition after the first 2
 207 partition specifications.
 208 It is worth noting at this time that the BSD scheme will automatically
 209 skip the 'c' partition by virtue of it referring to the entire disk.
 210 To create an image that is compatible with the qp120at disk, use the
 211 .Nm
 212 utility as follows:
 213 .Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
 214 -p freebsd-swap::20M -p- -p- -p- -p- -p freebsd-ufs:=usr-file-system.ufs \
 215 -o bsd.img
 216 .Pp
 217 For partitioning schemes that feature partition labels, the
 218 .Nm
 219 utility supports assigning labels to the partitions specified.
 220 In the following example the file system partition is labeled as 'backup':
 221 .Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img
 222 .Sh SEE ALSO
 223 .Xr gpart 8
 224 .Xr makefs 8
 225 .Xr mdconfig 8
 226 .Xr newfs 8
 227 .Sh HISTORY
 228 The
 229 .Nm
 230 utility first appeared in
 231 .Fx 10.1 .
 232 .Sh AUTHORS
 233 The
 234 .Nm
 235 utility and manpage were written by Marcel Moolenaar <marcelm@juniper.net>