1 .\" $NetBSD: makefs.8,v 1.33 2011/05/22 21:51:39 christos Exp $
3 .\" Copyright (c) 2001-2003 Wasabi Systems, Inc.
4 .\" All rights reserved.
6 .\" Written by Luke Mewburn for Wasabi Systems, Inc.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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.
43 .Nd create a file system image from a directory tree or a mtree manifest
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
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
63 .Ar directory | manifest
64 .Op Ar extra-directory ...
68 creates a file system image into
70 from the directory tree
72 or from the mtree manifest
74 If any optional directory trees are passed in the
76 arguments, then the directory tree of each argument will be merged
83 No special devices or privileges are required to perform this task.
85 The options are as follows:
88 Set the byte order of the image to
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
106 free blocks exist in the image.
109 suffix may be provided to indicate that
111 indicates a percentage of the calculated image size.
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
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 command line, not as a the
132 This option has no effect when the image is created from a mtree manifest
133 rather than a directory.
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.
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
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
160 (in the case of symbolic links).
163 is not provided, the current time will be used.
166 is not 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
171 free files (inodes) exist in the image.
174 suffix may be provided to indicate that
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
180 .It Fl m Ar maximum-size
181 Set the maximum size of the file system image to
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
188 and group database text file
192 rather than using the results from the system's
196 (and related) library calls.
198 Instead of creating the filesystem at the beginning of the file, start
204 .It Fl o Ar fs-options
205 Set file system specific options.
207 is a comma separated list of options.
208 Valid file system specific options are detailed below.
214 .It Fl R Ar roundup-size
215 Round the image up to
218 should be a multiple of the file system block size.
219 This option only applies to the
222 .It Fl S Ar sector-size
223 Set the file system sector size to
225 .\" XXX: next line also true for cd9660?
227 .It Fl s Ar image-size
228 Set the size of the file system image to
230 This is equivalent to setting both the minimum
234 sizes to the same value.
244 is not included in that size.
245 .It Fl T Ar timestamp
246 Specify a timestamp to be set for all filesystem files and directories
247 created so that repeatable builds are possible.
252 where the timestamps are derived from that file, or an integer
253 value interpreted as the number of seconds from the Epoch.
254 Note that timestamps specified in an
256 spec file, override the default timestamp.
261 The following file system types are supported:
262 .Bl -tag -width cd9660 -offset indent
264 BSD fast file system (default).
266 ISO 9660 file system.
268 FAT12, FAT16, or FAT32 file system.
270 ZFS pool containing one or more file systems.
273 Exclude file system nodes not explicitly listed in the specfile.
275 Create a sparse file for
277 This is useful for virtual machine images.
280 Where sizes are specified, a decimal number of bytes is expected.
281 Two or more numbers may be separated by an
283 to indicate a product.
284 Each number may have one of the following optional suffixes:
285 .Bl -tag -width 3n -offset indent -compact
287 Block; multiply by 512
289 Kibi; multiply by 1024 (1 KiB)
291 Mebi; multiply by 1048576 (1 MiB)
293 Gibi; multiply by 1073741824 (1 GiB)
295 Tebi; multiply by 1099511627776 (1 TiB)
297 Word; multiply by the number of bytes in an integer
301 .Ss FFS-specific options
303 images have ffs-specific optional parameters that may be provided.
304 Each of the options consists of a keyword, an equal sign
307 The following keywords are supported:
309 .Bl -tag -width optimization -offset indent -compact
311 Expected average file size.
313 Expected number of files per directory.
317 Bytes per inode. If unset, will allocate the minimum number of inodes to
318 represent the filesystem if no free space has been requested (free blocks
319 or minimum size set); otherwise the larger of the newfs defaults or what
320 is required by the free inode parameters if set.
324 Label name of the image.
326 Maximum blocks per file in a cylinder group.
330 Optimization preference; one of
337 Maximum total number of blocks in a cylinder group.
340 1 for FFS (default), 2 for UFS2.
342 0 for disable (default), 1 for enable
344 .Ss CD9660-specific options
346 images have ISO9660-specific optional parameters that may be
348 The arguments consist of a keyword and, optionally, an equal sign
351 The following keywords are supported:
353 .Bl -tag -width omit-trailing-period -offset indent -compact
354 .It Sy allow-deep-trees
355 Allow the directory structure to exceed the maximum specified in
357 .It Sy allow-illegal-chars
358 Allow illegal characters in filenames.
359 This option is not implemented.
360 .It Sy allow-lowercase
361 Allow lowercase characters in filenames.
362 This option is not implemented.
363 .It Sy allow-max-name
364 Allow 37 instead of 33 characters for filenames by omitting the
366 .It Sy allow-multidot
367 Allow multiple dots in a filename.
369 Application ID of the image.
377 Boot image directory.
378 This option is not implemented.
380 Write an MBR partition table to the image to allow older CHRP hardware to
382 .It Sy boot-load-segment
383 Set load segment for the boot image.
385 Filename of a boot image in the format
396 .It Sy generic-bootimage
397 Load a generic boot image into the first 32K of the cd9660 image.
398 .It Sy hard-disk-boot
399 Boot image is a hard disk image.
401 An integer representing the ISO 9660 interchange level where
410 .It Sy keep-bad-images
411 Do not discard images whose write was aborted due to an error.
412 For debugging purposes.
414 Label name of the image.
416 Boot image is not bootable.
421 .It Sy no-trailing-padding
422 Do not pad the image (apparently Linux needs the padding).
423 .It Sy omit-trailing-period
424 Omit trailing periods in filenames.
426 Set platform ID of section header entry of the boot image.
428 Preparer ID of the image.
430 Publisher ID of the image.
432 Use RockRidge extensions (for longer filenames, etc.).
434 Turns on verbose output.
436 Volume set identifier of the image.
438 .Ss msdos-specific options
440 images have MS-DOS-specific optional parameters that may be
442 The arguments consist of a keyword, an equal sign
445 The following keywords are supported (see
449 .Bl -tag -width omit-trailing-period -offset indent -compact
451 Location of the backup boot sector.
456 .It Cm bytes_per_sector
460 .It Cm directory_entries
465 FAT type (12, 16, or 32).
467 Preset drive parameters for standard format floppy disks
468 (160, 180, 320, 360, 640, 720, 1200, 1232, 1440, or 2880).
469 .It Cm hidden_sectors
472 Location of the info sector.
473 .It Cm media_descriptor
481 This option will be ignored if
483 is set to a positive number.
484 .It Cm reserved_sectors
486 .It Cm sectors_per_cluster
488 .It Cm sectors_per_fat
490 .It Cm sectors_per_track
499 .Ss zfs-specific options
500 Note: ZFS support is currently considered experimental.
501 Do not use it for anything critical.
505 contains a ZFS pool with a single vdev of type
507 The root dataset is always created implicitly and contains the entire input
508 directory tree unless additional datasets are specified using the options
511 The arguments consist of a keyword, an equal sign
514 The following keywords are supported:
516 .Bl -tag -width omit-trailing-period -offset indent -compact
518 The base-2 logarithm of the minimum block size.
519 Typical values are 9 (512B blocks) and 12 (4KB blocks).
520 The default value is 12.
522 The name of the bootable dataset for the pool.
523 Specifying this option causes the
525 property to be set in the created pool.
527 The size of metaslabs in the created pool.
530 allocates large (up to 512MB) metaslabs with the expectation that
531 the image will be auto-expanded upon first use.
532 This option allows the default heuristic to be overridden.
534 The name of the ZFS pool.
535 This option must be specified.
537 An implicit path prefix added to dataset mountpoints.
540 For creating bootable pools, the
544 At least one dataset must have a mountpoint equal to
547 Create an additional dataset.
548 This option may be specified multiple times.
549 The argument value must be of the form
550 .Ar <dataset>[;<prop1=v1>[;<prop2=v2>[;...]]] ,
553 is the name of the dataset and must belong to the pool's namespace.
554 For example, with a pool name of
556 all dataset names must be prefixed by
558 A dataset must exist at each level of the pool's namespace.
559 For example, to create
562 must be created as well.
564 The dataset mountpoints determine how the datasets are populated with
565 files from the staged directory tree.
566 Conceptually, all datasets are mounted before any are populated with files.
567 The root of the staged directory tree is mapped to
570 Dataset properties, as described in
572 may be specified following the dataset name.
573 The following properties may be set for a dataset:
575 .Bl -tag -compact -offset indent
597 and first appeared in
601 .Aq Mt lukem@NetBSD.org
606 .An Alan Perez-Rathke ,