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