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