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