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 November 15, 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 endian
  48 .Op Fl b Ar free-blocks
  49 .Op Fl d Ar debug-mask
  50 .Op Fl F Ar mtree-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 any optional directory trees are passed in the
  73 .Ar extra-directory
  74 arguments, 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 endian
  86 Set the byte order of the image to
  87 .Ar endian .
  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 mtree-specfile
 118 Use
 119 .Ar mtree-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 userdb-dir
 178 Use the user database text file
 179 .Pa master.passwd
 180 and group database text file
 181 .Pa group
 182 from
 183 .Ar userdb-dir ,
 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 a sparse file for
 230 .Sy ffs .
 231 This is useful for virtual machine images.
 232 .El
 233 .Pp
 234 Where sizes are specified, a decimal number of bytes is expected.
 235 Two or more numbers may be separated by an
 236 .Dq x
 237 to indicate a product.
 238 Each number may have one of the following optional suffixes:
 239 .Bl -tag -width 3n -offset indent -compact
 240 .It b
 241 Block; multiply by 512
 242 .It k
 243 Kibi; multiply by 1024 (1 KiB)
 244 .It m
 245 Mebi; multiply by 1048576 (1 MiB)
 246 .It g
 247 Gibi; multiply by 1073741824 (1 GiB)
 248 .It t
 249 Tebi; multiply by 1099511627776 (1 TiB)
 250 .It w
 251 Word; multiply by the number of bytes in an integer
 252 .El
 253 .\"
 254 .\"
 255 .Ss FFS-specific options
 256 .Sy ffs
 257 images have ffs-specific optional parameters that may be provided.
 258 Each of the options consists of a keyword, an equal sign
 259 .Pq Ql = ,
 260 and a value.
 261 The following keywords are supported:
 262 .Pp
 263 .Bl -tag -width optimization -offset indent -compact
 264 .It Sy avgfilesize
 265 Expected average file size.
 266 .It Sy avgfpdir
 267 Expected number of files per directory.
 268 .It Sy bsize
 269 Block size.
 270 .It Sy density
 271 Bytes per inode.
 272 .It Sy fsize
 273 Fragment size.
 274 .It Sy label
 275 Label name of the image.
 276 .It Sy maxbpg
 277 Maximum blocks per file in a cylinder group.
 278 .It Sy minfree
 279 Minimum % free.
 280 .It Sy optimization
 281 Optimization preference; one of
 282 .Ql space
 283 or
 284 .Ql time .
 285 .It Sy extent
 286 Maximum extent size.
 287 .It Sy maxbpcg
 288 Maximum total number of blocks in a cylinder group.
 289 .It Sy version
 290 UFS version.
 291 1 for FFS (default), 2 for UFS2.
 292 .El
 293 .Ss CD9660-specific options
 294 .Sy cd9660
 295 images have ISO9660-specific optional parameters that may be
 296 provided.
 297 The arguments consist of a keyword and, optionally, an equal sign
 298 .Pq Ql = ,
 299 and a value.
 300 The following keywords are supported:
 301 .Pp
 302 .Bl -tag -width omit-trailing-period -offset indent -compact
 303 .It Sy allow-deep-trees
 304 Allow the directory structure to exceed the maximum specified in
 305 the spec.
 306 .It Sy allow-illegal-chars
 307 Allow illegal characters in filenames. This option is not implemented.
 308 .It Sy allow-lowercase
 309 Allow lowercase characters in filenames. This option is not implemented.
 310 .It Sy allow-max-name
 311 Allow 37 instead of 33 characters for filenames by omitting the
 312 version id.
 313 .It Sy allow-multidot
 314 Allow multiple dots in a filename.
 315 .It Sy applicationid
 316 Application ID of the image.
 317 .It Sy archimedes
 318 Use the
 319 .Ql ARCHIMEDES
 320 extension to encode
 321 .Tn RISC OS
 322 metadata.
 323 .It Sy bootimagedir
 324 Boot image directory. This option is not implemented.
 325 .It Sy chrp-boot
 326 Write an MBR partition table to the image to allow older CHRP hardware to
 327 boot.
 328 .It Sy boot-load-segment
 329 Set load segment for the boot image.
 330 .It Sy bootimage
 331 Filename of a boot image in the format
 332 .Dq sysid;filename ,
 333 where
 334 .Dq sysid
 335 is one of
 336 .Ql i386 ,
 337 .Ql mac68k ,
 338 .Ql macppc ,
 339 or
 340 .Ql powerpc .
 341 .It Sy generic-bootimage
 342 Load a generic boot image into the first 32K of the cd9660 image.
 343 .It Sy hard-disk-boot
 344 Boot image is a hard disk image.
 345 .It Sy isolevel
 346 An integer representing the ISO 9660 interchange level where
 347 .Dq level
 348 is either
 349 .Ql 1
 350 or
 351 .Ql 2 .
 352 .Dq level
 353 .Ql 3
 354 is not implemented.
 355 .It Sy keep-bad-images
 356 Do not discard images whose write was aborted due to an error.
 357 For debugging purposes.
 358 .It Sy label
 359 Label name of the image.
 360 .It Sy no-boot
 361 Boot image is not bootable.
 362 .It Sy no-emul-boot
 363 Boot image is a
 364 .Dq no emulation
 365 ElTorito image.
 366 .It Sy no-trailing-padding
 367 Do not pad the image (apparently Linux needs the padding).
 368 .It Sy omit-trailing-period
 369 Omit trailing periods in filenames.
 370 .It Sy preparer
 371 Preparer ID of the image.
 372 .It Sy publisher
 373 Publisher ID of the image.
 374 .It Sy rockridge
 375 Use RockRidge extensions (for longer filenames, etc.).
 376 .It Sy verbose
 377 Turns on verbose output.
 378 .It Sy volumeid
 379 Volume set identifier of the image.
 380 .El
 381 .Sh SEE ALSO
 382 .Xr mtree 5 ,
 383 .Xr mtree 8 ,
 384 .Xr newfs 8
 385 .Sh HISTORY
 386 The
 387 .Nm
 388 utility appeared in
 389 .Nx 1.6 .
 390 .Sh AUTHORS
 391 .An Luke Mewburn Aq Mt lukem@NetBSD.org
 392 (original program),
 393 .An Daniel Watt ,
 394 .An Walter Deignan ,
 395 .An Ryan Gabrys ,
 396 .An Alan Perez-Rathke ,
 397 .An Ram Vedam
 398 (cd9660 support)