usr.sbin/makefs/makefs.8

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