usr.sbin/makefs/makefs.8

   1 .\"     $NetBSD: makefs.8,v 1.32 2009/01/20 20:47:25 bjh21 Exp $
   2 .\"
   3 .\" Copyright (c) 2001-2003 Wasabi Systems, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Luke Mewburn for Wasabi Systems, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"      This product includes software developed for the NetBSD Project by
  19 .\"      Wasabi Systems, Inc.
  20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  21 .\"    or promote products derived from this software without specific prior
  22 .\"    written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .\" $FreeBSD$
  37 .\"
  38 .Dd January 10, 2009
  39 .Dt MAKEFS 8
  40 .Os
  41 .Sh NAME
  42 .Nm makefs
  43 .Nd create a file system image from a directory tree or a mtree manifest
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Op Fl x
  47 .Op Fl B Ar byte-order
  48 .Op Fl b Ar free-blocks
  49 .Op Fl d Ar debug-mask
  50 .Op Fl F Ar specfile
  51 .Op Fl f Ar free-files
  52 .Op Fl M Ar minimum-size
  53 .Op Fl m Ar maximum-size
  54 .Op Fl N Ar userdb-dir
  55 .Op Fl o Ar fs-options
  56 .Op Fl S Ar sector-size
  57 .Op Fl s Ar image-size
  58 .Op Fl t Ar fs-type
  59 .Ar image-file
  60 .Ar directory | manifest
  61 .Sh DESCRIPTION
  62 The utility
  63 .Nm
  64 creates a file system image into
  65 .Ar image-file
  66 from the directory tree
  67 .Ar directory
  68 or from the mtree manifest
  69 .Ar manifest .
  70 No special devices or privileges are required to perform this task.
  71 .Pp
  72 The options are as follows:
  73 .Bl -tag -width flag
  74 .It Fl B Ar byte-order
  75 Set the byte order of the image to
  76 .Ar byte-order .
  77 Valid byte orders are
  78 .Ql 4321 ,
  79 .Ql big ,
  80 or
  81 .Ql be
  82 for big endian, and
  83 .Ql 1234 ,
  84 .Ql little ,
  85 or
  86 .Ql le
  87 for little endian.
  88 Some file systems may have a fixed byte order; in those cases this
  89 argument will be ignored.
  90 .It Fl b Ar free-blocks
  91 Ensure that a minimum of
  92 .Ar free-blocks
  93 free blocks exist in the image.
  94 An optional
  95 .Ql %
  96 suffix may be provided to indicate that
  97 .Ar free-blocks
  98 indicates a percentage of the calculated image size.
  99 .It Fl d Ar debug-mask
 100 Enable various levels of debugging, depending upon which bits are
 101 set in
 102 .Ar debug-mask .
 103 XXX: document these
 104 .It Fl F Ar specfile
 105 Use
 106 .Ar specfile
 107 as an
 108 .Xr mtree 8
 109 .Sq specfile
 110 specification.
 111 This option has no effect when the image is created from a mtree manifest
 112 rather than a directory.
 113 .Pp
 114 If a specfile entry exists in the underlying file system, its
 115 permissions and modification time will be used unless specifically
 116 overridden by the specfile.
 117 An error will be raised if the type of entry in the specfile
 118 conflicts with that of an existing entry.
 119 .Pp
 120 In the opposite case (where a specfile entry does not have an entry
 121 in the underlying file system) the following occurs:
 122 If the specfile entry is marked
 123 .Sy optional ,
 124 the specfile entry is ignored.
 125 Otherwise, the entry will be created in the image, and it is
 126 necessary to specify at least the following parameters in the
 127 specfile:
 128 .Sy type ,
 129 .Sy mode ,
 130 .Sy gname ,
 131 or
 132 .Sy gid ,
 133 and
 134 .Sy uname
 135 or
 136 .Sy uid ,
 137 .Sy device
 138 (in the case of block or character devices), and
 139 .Sy link
 140 (in the case of symbolic links).
 141 If
 142 .Sy time
 143 isn't provided, the current time will be used.
 144 If
 145 .Sy flags
 146 isn't provided, the current file flags will be used.
 147 Missing regular file entries will be created as zero-length files.
 148 .It Fl f Ar free-files
 149 Ensure that a minimum of
 150 .Ar free-files
 151 free files (inodes) exist in the image.
 152 An optional
 153 .Ql %
 154 suffix may be provided to indicate that
 155 .Ar free-files
 156 indicates a percentage of the calculated image size.
 157 .It Fl M Ar minimum-size
 158 Set the minimum size of the file system image to
 159 .Ar minimum-size .
 160 .It Fl m Ar maximum-size
 161 Set the maximum size of the file system image to
 162 .Ar maximum-size .
 163 An error will be raised if the target file system needs to be larger
 164 than this to accommodate the provided directory tree.
 165 .It Fl N Ar dbdir
 166 Use the user database text file
 167 .Pa master.passwd
 168 and group database text file
 169 .Pa group
 170 from
 171 .Ar dbdir ,
 172 rather than using the results from the system's
 173 .Xr getpwnam 3
 174 and
 175 .Xr getgrnam 3
 176 (and related) library calls.
 177 .It Fl o Ar fs-options
 178 Set file system specific options.
 179 .Ar fs-options
 180 is a comma separated list of options.
 181 Valid file system specific options are detailed below.
 182 .It Fl S Ar sector-size
 183 Set the file system sector size to
 184 .Ar sector-size .
 185 .\" XXX: next line also true for cd9660?
 186 Defaults to 512.
 187 .It Fl s Ar image-size
 188 Set the size of the file system image to
 189 .Ar image-size .
 190 .It Fl t Ar fs-type
 191 Create an
 192 .Ar fs-type
 193 file system image.
 194 The following file system types are supported:
 195 .Bl -tag -width cd9660 -offset indent
 196 .It Sy ffs
 197 BSD fast file system (default).
 198 .It Sy cd9660
 199 ISO 9660 file system.
 200 .El
 201 .It Fl x
 202 Exclude file system nodes not explicitly listed in the specfile.
 203 .El
 204 .Pp
 205 Where sizes are specified, a decimal number of bytes is expected.
 206 Two or more numbers may be separated by an
 207 .Dq x
 208 to indicate a product.
 209 Each number may have one of the following optional suffixes:
 210 .Bl -tag -width 3n -offset indent -compact
 211 .It b
 212 Block; multiply by 512
 213 .It k
 214 Kibi; multiply by 1024 (1 KiB)
 215 .It m
 216 Mebi; multiply by 1048576 (1 MiB)
 217 .It g
 218 Gibi; multiply by 1073741824 (1 GiB)
 219 .It t
 220 Tebi; multiply by 1099511627776 (1 TiB)
 221 .It w
 222 Word; multiply by the number of bytes in an integer
 223 .El
 224 .\"
 225 .\"
 226 .Ss FFS-specific options
 227 .Sy ffs
 228 images have ffs-specific optional parameters that may be provided.
 229 Each of the options consists of a keyword, an equal sign
 230 .Pq Ql = ,
 231 and a value.
 232 The following keywords are supported:
 233 .Pp
 234 .Bl -tag -width optimization -offset indent -compact
 235 .It Sy avgfilesize
 236 Expected average file size.
 237 .It Sy avgfpdir
 238 Expected number of files per directory.
 239 .It Sy bsize
 240 Block size.
 241 .It Sy density
 242 Bytes per inode.
 243 .It Sy fsize
 244 Fragment size.
 245 .It Sy label
 246 Label name of the image.
 247 .It Sy maxbpg
 248 Maximum blocks per file in a cylinder group.
 249 .It Sy minfree
 250 Minimum % free.
 251 .It Sy optimization
 252 Optimization preference; one of
 253 .Ql space
 254 or
 255 .Ql time .
 256 .It Sy extent
 257 Maximum extent size.
 258 .It Sy maxbpcg
 259 Maximum total number of blocks in a cylinder group.
 260 .It Sy version
 261 UFS version.
 262 1 for FFS (default), 2 for UFS2.
 263 .El
 264 .Ss CD9660-specific options
 265 .Sy cd9660
 266 images have ISO9660-specific optional parameters that may be
 267 provided.
 268 The arguments consist of a keyword and, optionally, an equal sign
 269 .Pq Ql = ,
 270 and a value.
 271 The following keywords are supported:
 272 .Pp
 273 .Bl -tag -width omit-trailing-period -offset indent -compact
 274 .It Sy allow-deep-trees
 275 Allow the directory structure to exceed the maximum specified in
 276 the spec.
 277 .\" .It Sy allow-illegal-chars
 278 .\" Unknown
 279 .\" .It Sy allow-lowercase
 280 .\" Unknown
 281 .It Sy allow-max-name
 282 Allow 37 instead of 33 characters for filenames by omitting the
 283 version id.
 284 .It Sy allow-multidot
 285 Allow multiple dots in a filename.
 286 .It Sy applicationid
 287 Application ID of the image.
 288 .It Sy archimedes
 289 Use the
 290 .Ql ARCHIMEDES
 291 extension to encode
 292 .Tn RISC OS
 293 metadata.
 294 .It Sy chrp-boot
 295 Write an MBR partition table to the image to allow older CHRP hardware to
 296 boot.
 297 .It Sy boot-load-segment
 298 Set load segment for the boot image.
 299 .It Sy bootimage
 300 Filename of a boot image in the format
 301 .Dq sysid;filename ,
 302 where
 303 .Dq sysid
 304 is one of
 305 .Ql i386 ,
 306 .Ql mac68k ,
 307 .Ql macppc ,
 308 or
 309 .Ql powerpc .
 310 .It Sy generic-bootimage
 311 Load a generic boot image into the first 32K of the cd9660 image.
 312 .It Sy hard-disk-boot
 313 Boot image is a hard disk image.
 314 .It Sy keep-bad-images
 315 Don't throw away images whose write was aborted due to an error.
 316 For debugging purposes.
 317 .It Sy label
 318 Label name of the image.
 319 .It Sy no-boot
 320 Boot image is not bootable.
 321 .It Sy no-emul-boot
 322 Boot image is a
 323 .Dq no emulation
 324 ElTorito image.
 325 .It Sy no-trailing-padding
 326 Do not pad the image (apparently Linux needs the padding).
 327 .\" .It Sy omit-trailing-period
 328 .\" Unknown
 329 .It Sy preparer
 330 Preparer ID of the image.
 331 .It Sy publisher
 332 Publisher ID of the image.
 333 .It Sy rockridge
 334 Use RockRidge extensions (for longer filenames, etc.).
 335 .It Sy volumeid
 336 Volume set identifier of the image.
 337 .El
 338 .Sh SEE ALSO
 339 .Xr mtree 5 ,
 340 .Xr mtree 8 ,
 341 .Xr newfs 8
 342 .Sh HISTORY
 343 The
 344 .Nm
 345 utility appeared in
 346 .Nx 1.6 .
 347 .Sh AUTHORS
 348 .An Luke Mewburn
 349 .Aq lukem@NetBSD.org
 350 (original program)
 351 .An Daniel Watt ,
 352 .An Walter Deignan ,
 353 .An Ryan Gabrys ,
 354 .An Alan Perez-Rathke ,
 355 .An Ram Vedam
 356 (cd9660 support)