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