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.Dd August 5, 2022 37.Dt MAKEFS 8 38.Os 39.Sh NAME 40.Nm makefs 41.Nd create a file system image from a directory tree or a mtree manifest 42.Sh SYNOPSIS 43.Nm 44.Op Fl DxZ 45.Op Fl B Ar endian 46.Op Fl b Ar free-blocks 47.Op Fl d Ar debug-mask 48.Op Fl F Ar mtree-specfile 49.Op Fl f Ar free-files 50.Op Fl M Ar minimum-size 51.Op Fl m Ar maximum-size 52.Op Fl N Ar userdb-dir 53.Op Fl O Ar offset 54.Op Fl o Ar fs-options 55.Op Fl R Ar roundup-size 56.Op Fl S Ar sector-size 57.Op Fl s Ar image-size 58.Op Fl T Ar timestamp 59.Op Fl t Ar fs-type 60.Ar image-file 61.Ar directory | manifest 62.Op Ar extra-directory ... 63.Sh DESCRIPTION 64The utility 65.Nm 66creates a file system image into 67.Ar image-file 68from the directory tree 69.Ar directory 70or from the mtree manifest 71.Ar manifest . 72If any optional directory trees are passed in the 73.Ar extra-directory 74arguments, then the directory tree of each argument will be merged 75into the 76.Ar directory 77or 78.Ar manifest 79first before creating 80.Ar image-file . 81No special devices or privileges are required to perform this task. 82.Pp 83The options are as follows: 84.Bl -tag -width flag 85.It Fl B Ar endian 86Set the byte order of the image to 87.Ar endian . 88Valid byte orders are 89.Ql 4321 , 90.Ql big , 91or 92.Ql be 93for big endian, and 94.Ql 1234 , 95.Ql little , 96or 97.Ql le 98for little endian. 99Some file systems may have a fixed byte order; in those cases this 100argument will be ignored. 101.It Fl b Ar free-blocks 102Ensure that a minimum of 103.Ar free-blocks 104free blocks exist in the image. 105An optional 106.Ql % 107suffix may be provided to indicate that 108.Ar free-blocks 109indicates a percentage of the calculated image size. 110.It Fl D 111Treat duplicate paths in an mtree manifest as warnings not error. 112.It Fl d Ar debug-mask 113Enable various levels of debugging, depending upon which bits are 114set in 115.Ar debug-mask . 116This option is intended for source debugging. 117.Ar debug-mask 118is a bit map defined in the header file 119.Ar makefs.h . 120See the source for usage, and look for defines starting with 121.Ar DEBUG_ . 122.It Fl F Ar mtree-specfile 123.Em This is almost certainly not the option you are looking for. 124To create an image from a list of files in an mtree format manifest, 125specify it as the last argument on the command line, not as a the 126argument to 127.Fl F . 128.Pp 129Use 130.Ar mtree-specfile 131as an 132.Xr mtree 8 133.Sq specfile 134specification. 135This option has no effect when the image is created from a mtree manifest 136rather than a directory. 137.Pp 138If a specfile entry exists in the underlying file system, its 139permissions and modification time will be used unless specifically 140overridden by the specfile. 141An error will be raised if the type of entry in the specfile 142conflicts with that of an existing entry. 143.Pp 144In the opposite case (where a specfile entry does not have an entry 145in the underlying file system) the following occurs: 146If the specfile entry is marked 147.Sy optional , 148the specfile entry is ignored. 149Otherwise, the entry will be created in the image, and it is 150necessary to specify at least the following parameters in the 151specfile: 152.Sy type , 153.Sy mode , 154.Sy gname , 155or 156.Sy gid , 157and 158.Sy uname 159or 160.Sy uid , 161and 162.Sy link 163(in the case of symbolic links). 164If 165.Sy time 166is not provided, the current time will be used. 167If 168.Sy flags 169is not provided, the current file flags will be used. 170Missing regular file entries will be created as zero-length files. 171.It Fl f Ar free-files 172Ensure that a minimum of 173.Ar free-files 174free files (inodes) exist in the image. 175An optional 176.Ql % 177suffix may be provided to indicate that 178.Ar free-files 179indicates a percentage of the calculated image size. 180.It Fl M Ar minimum-size 181Set the minimum size of the file system image to 182.Ar minimum-size . 183.It Fl m Ar maximum-size 184Set the maximum size of the file system image to 185.Ar maximum-size . 186An error will be raised if the target file system needs to be larger 187than this to accommodate the provided directory tree. 188.It Fl N Ar userdb-dir 189Use the user database text file 190.Pa master.passwd 191and group database text file 192.Pa group 193from 194.Ar userdb-dir , 195rather than using the results from the system's 196.Xr getpwnam 3 197and 198.Xr getgrnam 3 199(and related) library calls. 200.It Fl O Ar offset 201Instead of creating the filesystem at the beginning of the file, start 202at offset. 203Valid only for 204.Sy ffs 205and 206.Sy msdos . 207.It Fl o Ar fs-options 208Set file system specific options. 209.Ar fs-options 210is a comma separated list of options. 211Valid file system specific options are detailed below. 212.It Fl p 213Deprecated. 214See the 215.Fl Z 216flag. 217.It Fl R Ar roundup-size 218Round the image up to 219.Ar roundup-size . 220.Ar roundup-size 221should be a multiple of the file system block size. 222This option only applies to the 223.Sy ffs 224file system type. 225.It Fl S Ar sector-size 226Set the file system sector size to 227.Ar sector-size . 228.\" XXX: next line also true for cd9660? 229Defaults to 512. 230.It Fl s Ar image-size 231Set the size of the file system image to 232.Ar image-size . 233This is equivalent to setting both the minimum 234.Fl ( M ) 235and the maximum 236.Fl ( m ) 237sizes to the same value. 238For 239.Sy ffs 240and 241.Sy msdos 242the 243.Ar image-size 244does not include the 245.Ar offset . 246.Ar offset 247is not included in that size. 248.It Fl T Ar timestamp 249Specify a timestamp to be set for all filesystem files and directories 250created so that repeatable builds are possible. 251The 252.Ar timestamp 253can be a 254.Pa pathname , 255where the timestamps are derived from that file, or an integer 256value interpreted as the number of seconds from the Epoch. 257Note that timestamps specified in an 258.Xr mtree 5 259spec file, override the default timestamp. 260.It Fl t Ar fs-type 261Create an 262.Ar fs-type 263file system image. 264The following file system types are supported: 265.Bl -tag -width cd9660 -offset indent 266.It Sy ffs 267BSD fast file system (default). 268.It Sy cd9660 269ISO 9660 file system. 270.It Sy msdos 271FAT12, FAT16, or FAT32 file system. 272.It Sy zfs 273ZFS pool containing one or more file systems. 274.El 275.It Fl x 276Exclude file system nodes not explicitly listed in the specfile. 277.It Fl Z 278Create a sparse file for 279.Sy ffs . 280This is useful for virtual machine images. 281.El 282.Pp 283Where sizes are specified, a decimal number of bytes is expected. 284Two or more numbers may be separated by an 285.Dq x 286to indicate a product. 287Each number may have one of the following optional suffixes: 288.Bl -tag -width 3n -offset indent -compact 289.It b 290Block; multiply by 512 291.It k 292Kibi; multiply by 1024 (1 KiB) 293.It m 294Mebi; multiply by 1048576 (1 MiB) 295.It g 296Gibi; multiply by 1073741824 (1 GiB) 297.It t 298Tebi; multiply by 1099511627776 (1 TiB) 299.It w 300Word; multiply by the number of bytes in an integer 301.El 302.\" 303.\" 304.Ss FFS-specific options 305.Sy ffs 306images have ffs-specific optional parameters that may be provided. 307Each of the options consists of a keyword, an equal sign 308.Pq Ql = , 309and a value. 310The following keywords are supported: 311.Pp 312.Bl -tag -width optimization -offset indent -compact 313.It Sy avgfilesize 314Expected average file size. 315.It Sy avgfpdir 316Expected number of files per directory. 317.It Sy bsize 318Block size. 319.It Sy density 320Bytes per inode. If unset, will allocate the minimum number of inodes to 321represent the filesystem if no free space has been requested (free blocks 322or minimum size set); otherwise the larger of the newfs defaults or what 323is required by the free inode parameters if set. 324.It Sy fsize 325Fragment size. 326.It Sy label 327Label name of the image. 328.It Sy maxbpg 329Maximum blocks per file in a cylinder group. 330.It Sy minfree 331Minimum % free. 332.It Sy optimization 333Optimization preference; one of 334.Ql space 335or 336.Ql time . 337.It Sy extent 338Maximum extent size. 339.It Sy maxbpcg 340Maximum total number of blocks in a cylinder group. 341.It Sy version 342UFS version. 3431 for FFS (default), 2 for UFS2. 344.It Sy softupdates 3450 for disable (default), 1 for enable 346.El 347.Ss CD9660-specific options 348.Sy cd9660 349images have ISO9660-specific optional parameters that may be 350provided. 351The arguments consist of a keyword and, optionally, an equal sign 352.Pq Ql = , 353and a value. 354The following keywords are supported: 355.Pp 356.Bl -tag -width omit-trailing-period -offset indent -compact 357.It Sy allow-deep-trees 358Allow the directory structure to exceed the maximum specified in 359the spec. 360.It Sy allow-illegal-chars 361Allow illegal characters in filenames. 362This option is not implemented. 363.It Sy allow-lowercase 364Allow lowercase characters in filenames. 365This option is not implemented. 366.It Sy allow-max-name 367Allow 37 instead of 33 characters for filenames by omitting the 368version id. 369.It Sy allow-multidot 370Allow multiple dots in a filename. 371.It Sy applicationid 372Application ID of the image. 373.It Sy archimedes 374Use the 375.Ql ARCHIMEDES 376extension to encode 377.Tn RISC OS 378metadata. 379.It Sy bootimagedir 380Boot image directory. 381This option is not implemented. 382.It Sy chrp-boot 383Write an MBR partition table to the image to allow older CHRP hardware to 384boot. 385.It Sy boot-load-segment 386Set load segment for the boot image. 387.It Sy bootimage 388Filename of a boot image in the format 389.Dq sysid;filename , 390where 391.Dq sysid 392is one of 393.Ql efi , 394.Ql i386 , 395.Ql mac68k , 396.Ql macppc , 397or 398.Ql powerpc . 399.It Sy generic-bootimage 400Load a generic boot image into the first 32K of the cd9660 image. 401.It Sy hard-disk-boot 402Boot image is a hard disk image. 403.It Sy isolevel 404An integer representing the ISO 9660 interchange level where 405.Dq level 406is either 407.Ql 1 408or 409.Ql 2 . 410.Dq level 411.Ql 3 412is not implemented. 413.It Sy keep-bad-images 414Do not discard images whose write was aborted due to an error. 415For debugging purposes. 416.It Sy label 417Label name of the image. 418.It Sy no-boot 419Boot image is not bootable. 420.It Sy no-emul-boot 421Boot image is a 422.Dq no emulation 423ElTorito image. 424.It Sy no-trailing-padding 425Do not pad the image (apparently Linux needs the padding). 426.It Sy omit-trailing-period 427Omit trailing periods in filenames. 428.It Sy platformid 429Set platform ID of section header entry of the boot image. 430.It Sy preparer 431Preparer ID of the image. 432.It Sy publisher 433Publisher ID of the image. 434.It Sy rockridge 435Use RockRidge extensions (for longer filenames, etc.). 436.It Sy verbose 437Turns on verbose output. 438.It Sy volumeid 439Volume set identifier of the image. 440.El 441.Ss msdos-specific options 442.Sy msdos 443images have MS-DOS-specific optional parameters that may be 444provided. 445The arguments consist of a keyword, an equal sign 446.Pq Ql = , 447and a value. 448The following keywords are supported (see 449.Xr newfs_msdos 8 450for more details): 451.Pp 452.Bl -tag -width omit-trailing-period -offset indent -compact 453.It Cm backup_sector 454Location of the backup boot sector. 455.It Cm block_size 456Block size. 457.It Cm bootstrap 458Bootstrap file. 459.It Cm bytes_per_sector 460Bytes per sector. 461.It Cm create_size 462Create file size. 463.It Cm directory_entries 464Directory entries. 465.It Cm drive_heads 466Drive heads. 467.It Cm fat_type 468FAT type (12, 16, or 32). 469.It Cm floppy 470Preset drive parameters for standard format floppy disks 471(160, 180, 320, 360, 640, 720, 1200, 1232, 1440, or 2880). 472.It Cm hidden_sectors 473Hidden sectors. 474.It Cm info_sector 475Location of the info sector. 476.It Cm media_descriptor 477Media descriptor. 478.It Cm num_FAT 479Number of FATs. 480.It Cm OEM_string 481OEM string. 482.It Cm offset 483Offset in device. 484This option will be ignored if 485.Fl O 486is set to a positive number. 487.It Cm reserved_sectors 488Reserved sectors. 489.It Cm sectors_per_cluster 490Sectors per cluster. 491.It Cm sectors_per_fat 492Sectors per FAT. 493.It Cm sectors_per_track 494Sectors per track. 495.It Cm size 496File System size. 497.It Cm volume_id 498Volume ID. 499.It Cm volume_label 500Volume Label. 501.El 502.Ss zfs-specific options 503Note: ZFS support is currently considered experimental. 504Do not use it for anything critical. 505.Pp 506The image created by 507.Nm 508contains a ZFS pool with a single vdev of type 509.Ql disk . 510The root dataset is always created implicitly and contains the entire input 511directory tree unless additional datasets are specified using the options 512described below. 513.Pp 514The arguments consist of a keyword, an equal sign 515.Pq Ql = , 516and a value. 517The following keywords are supported: 518.Pp 519.Bl -tag -width omit-trailing-period -offset indent -compact 520.It ashift 521The base-2 logarithm of the minimum block size. 522Typical values are 9 (512B blocks) and 12 (4KB blocks). 523The default value is 12. 524.It bootfs 525The name of the bootable dataset for the pool. 526Specifying this option causes the 527.Ql bootfs 528property to be set in the created pool. 529.It mssize 530The size of metaslabs in the created pool. 531By default, 532.Nm 533allocates large (up to 512MB) metaslabs with the expectation that 534the image will be auto-expanded upon first use. 535This option allows the default heuristic to be overridden. 536.It poolname 537The name of the ZFS pool. 538This option must be specified. 539.It rootpath 540An implicit path prefix added to dataset mountpoints. 541By default it is 542.Pa /<poolname> . 543For creating bootable pools, the 544.Va rootpath 545should be set to 546.Pa / . 547At least one dataset must have a mountpoint equal to 548.Va rootpath . 549.It fs 550Create an additional dataset. 551This option may be specified multiple times. 552The argument value must be of the form 553.Ar <dataset>[;<prop1=v1>[;<prop2=v2>[;...]]] , 554where 555.Ar dataset 556is the name of the dataset and must belong to the pool's namespace. 557For example, with a pool name of 558.Ql test 559all dataset names must be prefixed by 560.Ql test/ . 561A dataset must exist at each level of the pool's namespace. 562For example, to create 563.Ql test/foo/bar , 564.Ql test/foo 565must be created as well. 566.Pp 567The dataset mountpoints determine how the datasets are populated with 568files from the staged directory tree. 569Conceptually, all datasets are mounted before any are populated with files. 570The root of the staged directory tree is mapped to 571.Va rootpath . 572.Pp 573Dataset properties, as described in 574.Xr zfsprops 8 , 575may be specified following the dataset name. 576The following properties may be set for a dataset: 577.Pp 578.Bl -tag -compact -offset indent 579.It atime 580.It canmount 581.It exec 582.It mountpoint 583.It setuid 584.El 585.El 586.Sh SEE ALSO 587.Xr mtree 5 , 588.Xr mtree 8 , 589.Xr newfs 8 , 590.Xr zfsconcepts 8 , 591.Xr zfsprops 8 , 592.Xr zpoolprops 8 593.Sh HISTORY 594The 595.Nm 596utility appeared in 597.Nx 1.6 . 598It was ported to 599.Fx 600and first appeared in 601.Fx 8.0 . 602.Sh AUTHORS 603.An Luke Mewburn 604.Aq Mt [email protected] 605(original program), 606.An Daniel Watt , 607.An Walter Deignan , 608.An Ryan Gabrys , 609.An Alan Perez-Rathke , 610.An Ram Vedam 611(cd9660 support), 612.An Christos Zoulas 613(msdos support), 614.An Mark Johnston 615(zfs support). 616