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 March 27, 2014
  28 .Dt MKIMG 1
  29 .Os
  30 .Sh NAME
  31 .Nm mkimg
  32 .Nd "utility to make a disk image"
  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 o Ar outfile
  41 .Op Fl v
  42 .Fl s Ar scheme
  43 .Fl p Ar partition
  44 .Op Fl p Ar partition ...
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility creates a disk image from the raw partition contents specified with
  49 the
  50 .Ar partition
  51 argument(s) and using the partitioning scheme specified with the
  52 .Ar scheme
  53 argument.
  54 The disk image is written to
  55 .Ar stdout
  56 by default or the file specified with the
  57 .Ar outfile
  58 argument.
  59 .Pp
  60 The disk image can be made bootable by specifying the scheme-specific boot
  61 block contents with the
  62 .Ar bootcode
  63 argument and,
  64 depending on the scheme,
  65 with a boot partition.
  66 The contents of such a boot partition is provided like any other partition
  67 and the
  68 .Nm
  69 utility does not treat it any differently from other partitions.
  70 .Pp
  71 Some partitioning schemes need a disk geometry and for those the
  72 .Nm
  73 utility accepts the
  74 .Ar tracksz
  75 and
  76 .Ar heads
  77 arguments, specifying the number of sectors per track and the number of
  78 heads per cylinder (resp.)
  79 .Pp
  80 Both the logical and physical sector size can be specified and for that the
  81 .Nm
  82 utility
  83 accepts the
  84 .Ar secsz
  85 and
  86 .Ar blksz
  87 arguments.
  88 The
  89 .Ar secsz
  90 argument is used to specify the logical sector size.
  91 This is the sector size reported by a disk when queried for its capacity.
  92 Modern disks use a larger sector size internally,
  93 referred to as block size by the
  94 .Nm
  95 utility and this can be specified by the
  96 .Ar blksz
  97 argument.
  98 The
  99 .Nm
 100 utility will use the (physical) block size to determine the start of
 101 partitions and to round the size of the disk image.
 102 .Pp
 103 The
 104 .Op Fl v
 105 option increases the level of output that the
 106 .Nm
 107 utility prints.
 108 .Pp
 109 For a complete list of supported partitioning schemes or for a detailed
 110 description of how to specify partitions, run the
 111 .Nm
 112 utility without any arguments.
 113 .Sh EXAMPLES
 114 To create a bootable disk image that is partitioned using the GPT scheme and
 115 containing a root file system that was previously created using
 116 .Xr makefs
 117 and also containing a swap partition, run the
 118 .Nm
 119 utility as follows:
 120 .Dl % mkimg -s gpt -b /boot/pmbr -p freebsd-boot:=/boot/gptboot \
 121 -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G \
 122 -o gpt.img
 123 .Pp
 124 A nested partitioning scheme is created by running the
 125 .Nm
 126 utility twice.
 127 The output of the first will be fed as the contents of a partition to the
 128 second.
 129 This can be done using a temporary file, like so:
 130 .Dl % mkimg -s bsd -b /boot/boot -p freebsd-ufs:=root-file-system.ufs \
 131 -p freebsd-swap::1G -o /tmp/bsd.img
 132 .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:=/tmp/bsd.img -o mbr-bsd.img
 133 .Pp
 134 Alternatively, the
 135 .Nm
 136 utility can be run in a cascaded fashion, whereby the output of the
 137 first is fed directly into the second.
 138 To do this, run the
 139 .Nm
 140 utility as follows:
 141 .Dl % mkimg -s mbr -b /boot/mbr -p freebsd:-'mkimg -s bsd -b /boot/boot \
 142 -p freebsd-ufs:=root-file-system.ufs -p freebsd-swap::1G' -o mbr-bsd.img
 143 .Pp
 144 For partitioning schemes that feature partition labels, the
 145 .Nm
 146 utility supports assigning labels to the partitions specified.
 147 In the following example the file system partition is labeled as 'backup':
 148 .Dl % mkimg -s gpt -p freebsd-ufs/backup:=file-system.ufs -o gpt.img
 149 .Sh SEE ALSO
 150 .Xr gpart 8
 151 .Xr makefs 8
 152 .Xr mdconfig 8
 153 .Xr newfs 8
 154 .Sh HISTORY
 155 The
 156 .Nm
 157 utility appeared in
 158 .Fx 11.0
 159 .Sh AUTHORS
 160 The
 161 .Nm
 162 utility and manpage were written by Marcel Moolenaar <marcelm@juniper.net>