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 August 16, 2013
  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 DxZ
  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 .Op Ar extra-directory ...
  62 .Sh DESCRIPTION
  63 The utility
  64 .Nm
  65 creates a file system image into
  66 .Ar image-file
  67 from the directory tree
  68 .Ar directory
  69 or from the mtree manifest
  70 .Ar manifest .
  71 If optional directory tree
  72 .Ar extra-directory
  73 is passed, then the directory tree of each argument will be merged
  74 into the
  75 .Ar directory
  76 or
  77 .Ar manifest
  78 first before creating
  79 .Ar image-file .
  80 No special devices or privileges are required to perform this task.
  81 .Pp
  82 The options are as follows:
  83 .Bl -tag -width flag
  84 .It Fl B Ar byte-order
  85 Set the byte order of the image to
  86 .Ar byte-order .
  87 Valid byte orders are
  88 .Ql 4321 ,
  89 .Ql big ,
  90 or
  91 .Ql be
  92 for big endian, and
  93 .Ql 1234 ,
  94 .Ql little ,
  95 or
  96 .Ql le
  97 for little endian.
  98 Some file systems may have a fixed byte order; in those cases this
  99 argument will be ignored.
 100 .It Fl b Ar free-blocks
 101 Ensure that a minimum of
 102 .Ar free-blocks
 103 free blocks exist in the image.
 104 An optional
 105 .Ql %
 106 suffix may be provided to indicate that
 107 .Ar free-blocks
 108 indicates a percentage of the calculated image size.
 109 .It Fl D
 110 Treat duplicate paths in an mtree manifest as warnings not error.
 111 .It Fl d Ar debug-mask
 112 Enable various levels of debugging, depending upon which bits are
 113 set in
 114 .Ar debug-mask .
 115 XXX: document these
 116 .It Fl F Ar specfile
 117 Use
 118 .Ar specfile
 119 as an
 120 .Xr mtree 8
 121 .Sq specfile
 122 specification.
 123 This option has no effect when the image is created from a mtree manifest
 124 rather than a directory.
 125 .Pp
 126 If a specfile entry exists in the underlying file system, its
 127 permissions and modification time will be used unless specifically
 128 overridden by the specfile.
 129 An error will be raised if the type of entry in the specfile
 130 conflicts with that of an existing entry.
 131 .Pp
 132 In the opposite case (where a specfile entry does not have an entry
 133 in the underlying file system) the following occurs:
 134 If the specfile entry is marked
 135 .Sy optional ,
 136 the specfile entry is ignored.
 137 Otherwise, the entry will be created in the image, and it is
 138 necessary to specify at least the following parameters in the
 139 specfile:
 140 .Sy type ,
 141 .Sy mode ,
 142 .Sy gname ,
 143 or
 144 .Sy gid ,
 145 and
 146 .Sy uname
 147 or
 148 .Sy uid ,
 149 and
 150 .Sy link
 151 (in the case of symbolic links).
 152 If
 153 .Sy time
 154 isn't provided, the current time will be used.
 155 If
 156 .Sy flags
 157 isn't provided, the current file flags will be used.
 158 Missing regular file entries will be created as zero-length files.
 159 .It Fl f Ar free-files
 160 Ensure that a minimum of
 161 .Ar free-files
 162 free files (inodes) exist in the image.
 163 An optional
 164 .Ql %
 165 suffix may be provided to indicate that
 166 .Ar free-files
 167 indicates a percentage of the calculated image size.
 168 .It Fl M Ar minimum-size
 169 Set the minimum size of the file system image to
 170 .Ar minimum-size .
 171 .It Fl m Ar maximum-size
 172 Set the maximum size of the file system image to
 173 .Ar maximum-size .
 174 An error will be raised if the target file system needs to be larger
 175 than this to accommodate the provided directory tree.
 176 .It Fl N Ar dbdir
 177 Use the user database text file
 178 .Pa master.passwd
 179 and group database text file
 180 .Pa group
 181 from
 182 .Ar dbdir ,
 183 rather than using the results from the system's
 184 .Xr getpwnam 3
 185 and
 186 .Xr getgrnam 3
 187 (and related) library calls.
 188 .It Fl o Ar fs-options
 189 Set file system specific options.
 190 .Ar fs-options
 191 is a comma separated list of options.
 192 Valid file system specific options are detailed below.
 193 .It Fl p
 194 Deprecated.
 195 See the
 196 .Fl Z
 197 flag.
 198 .It Fl S Ar sector-size
 199 Set the file system sector size to
 200 .Ar sector-size .
 201 .\" XXX: next line also true for cd9660?
 202 Defaults to 512.
 203 .It Fl s Ar image-size
 204 Set the size of the file system image to
 205 .Ar image-size .
 206 .It Fl t Ar fs-type
 207 Create an
 208 .Ar fs-type
 209 file system image.
 210 The following file system types are supported:
 211 .Bl -tag -width cd9660 -offset indent
 212 .It Sy ffs
 213 BSD fast file system (default).
 214 .It Sy cd9660
 215 ISO 9660 file system.
 216 .El
 217 .It Fl x
 218 Exclude file system nodes not explicitly listed in the specfile.
 219 .It Fl Z
 220 Create the image as a sparse file.
 221 .El
 222 .Pp
 223 Where sizes are specified, a decimal number of bytes is expected.
 224 Two or more numbers may be separated by an
 225 .Dq x
 226 to indicate a product.
 227 Each number may have one of the following optional suffixes:
 228 .Bl -tag -width 3n -offset indent -compact
 229 .It b
 230 Block; multiply by 512
 231 .It k
 232 Kibi; multiply by 1024 (1 KiB)
 233 .It m
 234 Mebi; multiply by 1048576 (1 MiB)
 235 .It g
 236 Gibi; multiply by 1073741824 (1 GiB)
 237 .It t
 238 Tebi; multiply by 1099511627776 (1 TiB)
 239 .It w
 240 Word; multiply by the number of bytes in an integer
 241 .El
 242 .\"
 243 .\"
 244 .Ss FFS-specific options
 245 .Sy ffs
 246 images have ffs-specific optional parameters that may be provided.
 247 Each of the options consists of a keyword, an equal sign
 248 .Pq Ql = ,
 249 and a value.
 250 The following keywords are supported:
 251 .Pp
 252 .Bl -tag -width optimization -offset indent -compact
 253 .It Sy avgfilesize
 254 Expected average file size.
 255 .It Sy avgfpdir
 256 Expected number of files per directory.
 257 .It Sy bsize
 258 Block size.
 259 .It Sy density
 260 Bytes per inode.
 261 .It Sy fsize
 262 Fragment size.
 263 .It Sy label
 264 Label name of the image.
 265 .It Sy maxbpg
 266 Maximum blocks per file in a cylinder group.
 267 .It Sy minfree
 268 Minimum % free.
 269 .It Sy optimization
 270 Optimization preference; one of
 271 .Ql space
 272 or
 273 .Ql time .
 274 .It Sy extent
 275 Maximum extent size.
 276 .It Sy maxbpcg
 277 Maximum total number of blocks in a cylinder group.
 278 .It Sy version
 279 UFS version.
 280 1 for FFS (default), 2 for UFS2.
 281 .El
 282 .Ss CD9660-specific options
 283 .Sy cd9660
 284 images have ISO9660-specific optional parameters that may be
 285 provided.
 286 The arguments consist of a keyword and, optionally, an equal sign
 287 .Pq Ql = ,
 288 and a value.
 289 The following keywords are supported:
 290 .Pp
 291 .Bl -tag -width omit-trailing-period -offset indent -compact
 292 .It Sy allow-deep-trees
 293 Allow the directory structure to exceed the maximum specified in
 294 the spec.
 295 .\" .It Sy allow-illegal-chars
 296 .\" Unknown
 297 .\" .It Sy allow-lowercase
 298 .\" Unknown
 299 .It Sy allow-max-name
 300 Allow 37 instead of 33 characters for filenames by omitting the
 301 version id.
 302 .It Sy allow-multidot
 303 Allow multiple dots in a filename.
 304 .It Sy applicationid
 305 Application ID of the image.
 306 .It Sy archimedes
 307 Use the
 308 .Ql ARCHIMEDES
 309 extension to encode
 310 .Tn RISC OS
 311 metadata.
 312 .It Sy chrp-boot
 313 Write an MBR partition table to the image to allow older CHRP hardware to
 314 boot.
 315 .It Sy boot-load-segment
 316 Set load segment for the boot image.
 317 .It Sy bootimage
 318 Filename of a boot image in the format
 319 .Dq sysid;filename ,
 320 where
 321 .Dq sysid
 322 is one of
 323 .Ql i386 ,
 324 .Ql mac68k ,
 325 .Ql macppc ,
 326 or
 327 .Ql powerpc .
 328 .It Sy generic-bootimage
 329 Load a generic boot image into the first 32K of the cd9660 image.
 330 .It Sy hard-disk-boot
 331 Boot image is a hard disk image.
 332 .It Sy keep-bad-images
 333 Do not throw away images whose write was aborted due to an error.
 334 For debugging purposes.
 335 .It Sy label
 336 Label name of the image.
 337 .It Sy no-boot
 338 Boot image is not bootable.
 339 .It Sy no-emul-boot
 340 Boot image is a
 341 .Dq no emulation
 342 ElTorito image.
 343 .It Sy no-trailing-padding
 344 Do not pad the image (apparently Linux needs the padding).
 345 .\" .It Sy omit-trailing-period
 346 .\" Unknown
 347 .It Sy preparer
 348 Preparer ID of the image.
 349 .It Sy publisher
 350 Publisher ID of the image.
 351 .It Sy rockridge
 352 Use RockRidge extensions (for longer filenames, etc.).
 353 .It Sy volumeid
 354 Volume set identifier of the image.
 355 .El
 356 .Sh SEE ALSO
 357 .Xr mtree 5 ,
 358 .Xr mtree 8 ,
 359 .Xr newfs 8
 360 .Sh HISTORY
 361 The
 362 .Nm
 363 utility appeared in
 364 .Nx 1.6 .
 365 .Sh AUTHORS
 366 .An Luke Mewburn
 367 .Aq lukem@NetBSD.org
 368 (original program)
 369 .An Daniel Watt ,
 370 .An Walter Deignan ,
 371 .An Ryan Gabrys ,
 372 .An Alan Perez-Rathke ,
 373 .An Ram Vedam
 374 (cd9660 support)