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