1.\"	$NetBSD: makefs.8,v 1.74 2026/01/10 08:58:47 tsutsui 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 January 10, 2026
 37.Dt MAKEFS 8
 38.Os
 39.Sh NAME
 40.Nm makefs
 41.Nd create a file system image from a directory tree
 42.Sh SYNOPSIS
 43.Nm
 44.Op Fl LrxZ
 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 S Ar sector-size
 56.Op Fl s Ar image-size
 57.Op Fl T Ar timestamp
 58.Op Fl t Ar fs-type
 59.Ar image-file
 60.Ar directory
 61.Op Ar extra-directory ...
 62.Sh DESCRIPTION
 63The utility
 64.Nm
 65creates a file system image into
 66.Ar image-file
 67from the directory tree
 68.Ar directory .
 69If any optional directory trees are passed in the
 70.Ar extra-directory
 71arguments, then the directory tree of each argument will be merged
 72into the
 73.Ar directory
 74first before creating
 75.Ar image-file .
 76No special devices or privileges are required to perform this task.
 77.Pp
 78The options are as follows:
 79.Bl -tag -width flag
 80.It Fl B Ar endian
 81Set the byte order of the image to
 82.Ar endian .
 83Valid byte orders are
 84.Ql 4321 ,
 85.Ql big ,
 86or
 87.Ql be
 88for big endian, and
 89.Ql 1234 ,
 90.Ql little ,
 91or
 92.Ql le
 93for little endian.
 94Some file systems may have a fixed byte order; in those cases this
 95argument will be ignored.
 96.It Fl b Ar free-blocks
 97Ensure that a minimum of
 98.Ar free-blocks
 99free blocks exist in the image.
100An optional
101.Ql %
102suffix may be provided to indicate that
103.Ar free-blocks
104indicates a percentage of the calculated image size.
105.It Fl d Ar debug-mask | comma-separated-debug-option
106Enable various levels of debugging, depending upon which bits are
107set in
108.Ar debug-mask .
109The mask can also be set by specifying a comma separated list of debugging
110options.
111These are:
112.Bl -tag -width X -offset indent -compact
113.It Ar debug_time
114Print the time it takes to perform each step.
115.It Ar debug_walk_dir
116Print each directory as it gets processed.
117.It Ar debug_walk_dir_node
118Print each file as it gets processed.
119.It Ar debug_walk_dir_linkcheck
120Print file information for files that have a link count > 1.
121.It Ar debug_dump_fsnodes
122Dump information about the filesystem nodes.
123.It Ar debug_dump_fsnodes_verbose
124Enable more detail if
125.Dv debug_dump_fsnodes
126is enabled.
127.It Ar debug_fs_parse_opts
128Print debugging information about specific filesystem option parsing.
129.It Ar debug_fs_makefs
130Print nodes as they are created and enable buffer consistency checks.
131.It Ar debug_fs_validate
132Enable file-system specific validation (ffs only).
133.It Ar debug_fs_create_image
134Print image file creation stats (ffs only).
135.It Ar debug_fs_size_dir
136Print directory size information (ffs only).
137.It Ar debug_fs_size_dir_node
138Print directory size information per node (ffs only).
139.It Ar debug_fs_size_dir_add_dirent
140Print directory size information as entries are added (ffs only).
141.It Ar debug_fs_populate
142Print information at each directory population pass (ffs only).
143.It Ar debug_fs_populate_dirbuf
144Dump the directory buffer (ffs only).
145.It Ar debug_fs_populate_node
146Print information about each file during directory population (ffs only).
147.It Ar debug_fs_write_file
148Print buffer informaion when writing files (ffs only).
149.It Ar debug_fs_write_file_block
150Print block information when writing files (ffs only).
151.It Ar debug_fs_make_dirbuf
152Print directory buffer information (ffs only).
153.It Ar debug_fs_write_inode
154Print inode information (ffs only).
155.It Ar debug_buf_bread
156Print block buffer information (ffs only).
157.It Ar debug_buf_bwrite
158Print block write information (ffs only).
159.It Ar debug_buf_getblk
160Print block allocaion information (ffs only).
161.It Ar debug_apply_specfile
162Print information about each directory in the specfile.
163.It Ar debug_apply_specentry
164Print information about each entry in the specfile.
165.It Ar debug_apply_speconly
166Debug the
167.Fl x
168special file exclusion.
169.El
170.It Fl F Ar mtree-specfile
171Use
172.Ar mtree-specfile
173as an
174.Xr mtree 8
175.Sq specfile
176specification.
177.Pp
178If a specfile entry exists in the underlying file system, its
179permissions and modification time will be used unless specifically
180overridden by the specfile.
181An error will be raised if the type of entry in the specfile
182conflicts with that of an existing entry.
183.Pp
184In the opposite case (where a specfile entry does not have an entry
185in the underlying file system) the following occurs:
186If the specfile entry is marked
187.Sy optional ,
188the specfile entry is ignored.
189Otherwise, the entry will be created in the image, and it is
190necessary to specify at least the following parameters in the
191specfile:
192.Sy type ,
193.Sy mode ,
194.Sy gname ,
195or
196.Sy gid ,
197and
198.Sy uname
199or
200.Sy uid ,
201.Sy device
202(in the case of block or character devices), and
203.Sy link
204(in the case of symbolic links).
205If
206.Sy time
207isn't provided, the current time will be used.
208If
209.Sy flags
210isn't provided, the current file flags will be used.
211Missing regular file entries will be created as zero-length files.
212.It Fl f Ar free-files
213Ensure that a minimum of
214.Ar free-files
215free files (inodes) exist in the image.
216An optional
217.Ql %
218suffix may be provided to indicate that
219.Ar free-files
220indicates a percentage of the calculated image size.
221.It Fl L
222All symbolic links are followed.
223.It Fl M Ar minimum-size
224Set the minimum size of the file system image to
225.Ar minimum-size .
226.It Fl m Ar maximum-size
227Set the maximum size of the file system image to
228.Ar maximum-size .
229An error will be raised if the target file system needs to be larger
230than this to accommodate the provided directory tree.
231.It Fl N Ar userdb-dir
232Use the user database text file
233.Pa master.passwd
234and group database text file
235.Pa group
236from
237.Ar userdb-dir ,
238rather than using the results from the system's
239.Xr getpwnam 3
240and
241.Xr getgrnam 3
242(and related) library calls.
243.It Fl O Ar offset
244Instead of creating the file system at the beginning of the file, start
245at offset.
246Valid only for
247.Sy ffs
248and
249.Sy msdos .
250.It Fl o Ar fs-options
251Set file system specific options.
252.Ar fs-options
253is a comma separated list of options.
254Valid file system specific options are detailed below.
255.It Fl r
256When merging multiple directories replace duplicate files with the last found.
257.It Fl S Ar sector-size
258Set the file system sector size to
259.Ar sector-size .
260Defaults to 512 for most file systems, but is 2048 for
261.Sy cd9660
262and
263.Sy udf
264for CD/DVD/BD optical media types.
265.It Fl s Ar image-size
266Set the size of the file system image to
267.Ar image-size .
268This is equivalent of setting both the minimum
269.Fl ( M )
270and the maximum
271.Fl ( m )
272sizes to
273.Ar image-size .
274For
275.Sy ffs
276and
277.Sy msdos
278the
279.Ar offset
280is not included on that size.
281.It Fl T Ar timestamp
282Specify a timestamp to be set for all file system files and directories
283created so that repeatable builds are possible.
284The
285.Ar timestamp
286can be a
287.Pa pathname ,
288where the timestamps are derived from that file, a parseable date
289for
290.Xr parsedate 3
291(this option is not yet available in the tools build), or an integer
292value interpreted as the number of seconds from the Epoch.
293Note that timestamps specified in an
294.Xr mtree 5
295spec file, override the default timestamp.
296When this option is enabled, file systems that regularly use
297.Xr localtime 3
298to convert times to the native format (such as udf and cd9660), use
299.Xr gmtime 3
300instead with the specified timestamps so that they are immune to
301timezone changes and get consistent timestamps.
302.It Fl t Ar fs-type
303Create an
304.Ar fs-type
305file system image.
306The following file system types are supported:
307.Bl -tag -width cd9660 -offset indent
308.It Sy cd9660
309ISO 9660 file system.
310.It Sy chfs
311Chip flash file system.
312.It Sy ffs
313BSD fast file system (default).
314.It Sy msdos
315FAT12, FAT16, or FAT32 file system.
316.It Sy udf
317ISO/Ecma UDF file system.
318.It Sy v7fs
3197th Edition(V7) file system.
320.El
321.It Fl x
322Exclude file system nodes not explicitly listed in the specfile.
323Repeating this flag causes
324.Nm
325to print a warning for each missing system nodes and exit with an error code
326if there are any missing.
327.It Fl Z
328Create a sparse file for
329.Sy ffs .
330This is useful for virtual machine images.
331.El
332.Pp
333Where sizes are specified, a decimal number of bytes is expected.
334Two or more numbers may be separated by an
335.Sq x
336to indicate a product.
337Each number may have one of the following optional suffixes:
338.Bl -tag -width 3n -offset indent -compact
339.It b
340Block; multiply by 512
341.It k
342Kibi; multiply by 1024 (1 KiB)
343.It m
344Mebi; multiply by 1048576 (1 MiB)
345.It g
346Gibi; multiply by 1073741824 (1 GiB)
347.It t
348Tebi; multiply by 1099511627776 (1 TiB)
349.It w
350Word; multiply by the number of bytes in an integer
351.El
352.\"
353.\"
354.Ss FFS-specific options
355.Sy ffs
356images have ffs-specific optional parameters that may be provided.
357Each of the options consists of a keyword, an equal sign
358.Pq Ql = ,
359and a value.
360The following keywords are supported:
361.Pp
362.Bl -tag -width optimization -offset indent -compact
363.It Sy avgfilesize
364Expected average file size.
365.It Sy avgfpdir
366Expected number of files per directory.
367.It Sy bsize
368Block size.
369.It Sy density
370Bytes per inode.
371.It Sy extattr
372UFS2 with extended attributes.
373.It Sy extent
374Maximum extent size.
375.It Sy fsize
376Fragment size.
377.It Sy label
378Label name of the image.
379.It Sy maxbpcg
380Maximum total number of blocks in a cylinder group.
381.It Sy maxbpg
382Maximum blocks per file in a cylinder group.
383.It Sy minfree
384Minimum % free.
385.It Sy optimization
386Optimization preference; one of
387.Ql space
388or
389.Ql time .
390.It Sy version
391File system format version, compatible with the
392.Fl O
393option of
394.Xr newfs 8 .
3950 for FFSv1 with the old level 1 format.
3961 for FFSv1 (default, level 4), and
3972 for FFSv2 (UFS2).
398.El
399.Ss CD9660-specific options
400.Sy cd9660
401images have ISO9660-specific optional parameters that may be
402provided.
403The arguments consist of a keyword and, optionally, an equal sign
404.Pq Ql = ,
405and a value.
406The following keywords are supported:
407.Pp
408.Bl -tag -width omit-trailing-period -offset indent -compact
409.It Sy allow-deep-trees
410Allow the directory structure to exceed the maximum specified in
411the spec.
412.\" .It Sy allow-illegal-chars
413.\" Unknown
414.\" .It Sy allow-lowercase
415.\" Unknown
416.It Sy allow-max-name
417Allow 37 instead of 33 characters for filenames by omitting the
418version ID.
419.It Sy allow-multidot
420Allow multiple dots in a filename.
421.It Sy applicationid
422Application ID of the image.
423.It Sy archimedes
424Use the
425.Ql ARCHIMEDES
426extension to encode
427.Tn RISC OS
428metadata.
429.It Sy boot-load-segment
430Set load segment for the boot image.
431.It Sy bootimage
432Filename of a boot image in the format
433.Dq sysid;filename ,
434where
435.Dq sysid
436is one of
437.Ql efi ,
438.Ql i386 ,
439.Ql mac68k ,
440.Ql macppc ,
441or
442.Ql powerpc .
443.It Sy chrp-boot
444Write an MBR partition table to the image to allow older CHRP hardware to
445boot.
446.It Sy generic-bootimage
447Load a generic boot image into the first 32K of the cd9660 image.
448.It Sy hard-disk-boot
449Boot image is a hard disk image.
450.It Sy keep-bad-images
451Don't throw away images whose write was aborted due to an error.
452For debugging purposes.
453.It Sy label
454Label name of the image.
455.It Sy no-boot
456Boot image is not bootable.
457.It Sy no-emul-boot
458Boot image is a
459.Dq no emulation
460ElTorito image.
461.It Sy no-trailing-padding
462Do not pad the image (apparently Linux needs the padding).
463.\" .It Sy omit-trailing-period
464.\" Unknown
465.It Sy platformid
466Set platform ID of section header entry of the boot image.
467.It Sy preparer
468Preparer ID of the image.
469.It Sy publisher
470Publisher ID of the image.
471.It Sy rockridge
472Use RockRidge extensions (for longer filenames, etc.).
473.It Sy volumeid
474Volume set identifier of the image.
475.El
476.Ss CHFS-specific options
477.Sy chfs
478images have chfs-specific optional parameters that may be provided.
479Each of the options consists of a keyword, an equal sign
480.Pq Ql = ,
481and a value.
482The following keywords are supported:
483.Pp
484.Bl -tag -width optimization -offset indent -compact
485.It Sy pagesize
486Pagesize.
487.It Sy erasesize
488Erase block size of the media.
489.It Sy mediatype
490Type of the media.
491NOR: 0 or NAND: 1.
492.El
493.Ss msdos-specific options
494.Sy msdos
495images have MS-DOS-specific optional parameters that may be
496provided.
497The arguments consist of a keyword, an equal sign
498.Pq Ql = ,
499and a value.
500The following keywords are supported (see
501.Xr newfs_msdos 8
502for more details):
503.Pp
504.Bl -tag -width omit-trailing-period -offset indent -compact
505.It Cm backup_sector
506Location of the backup boot sector.
507.It Cm block_size
508Block size.
509.It Cm bootstrap
510Bootstrap file.
511.It Cm bytes_per_sector
512Bytes per sector.
513.It Cm create_size
514Create file size.
515.It Cm directory_entries
516Directory entries.
517.It Cm drive_heads
518Drive heads.
519.It Cm fat_type
520FAT type (12, 16, or 32).
521.It Cm floppy
522Preset drive parameters for standard format floppy disks
523(160, 180, 320, 360, 640, 720, 1200, 1232, 1440, or 2880).
524.It Cm hidden_sectors
525Hidden sectors.
526.It Cm info_sector
527Location of the info sector.
528.It Cm media_descriptor
529Media descriptor.
530.It Cm num_FAT
531Number of FATs.
532.It Cm OEM_string
533OEM string.
534.It Cm offset
535Offset in device.
536.It Cm reserved_sectors
537Reserved sectors.
538.It Cm sectors_per_cluster
539Sectors per cluster.
540.It Cm sectors_per_fat
541Sectors per FAT.
542.It Cm sectors_per_track
543Sectors per track.
544.It Cm size
545File System size.
546.It Cm volume_id
547Volume ID.
548.It Cm volume_label
549Volume Label.
550.El
551.Ss V7FS-specific options
552The following keywords are supported:
553.Pp
554.Bl -tag -width optimization -offset indent -compact
555.It Sy pdp
556PDP endian.
557.It Sy progress
558Display a progress meter for the file system construction and file
559population.
560.El
561.Ss UDF-specific options
562.Nm
563supports besides writing to image files also direct formatting of disc
564partitions and optical media.
565Optical media will auto configure settings.
566The following udf-specific optional parameters may be provided.
567Each of the options consists of a keyword, an equal sign
568.Pq Ql = ,
569and a value.
570The following keywords are supported:
571.Pp
572.Bl -tag -width optimization -offset indent -compact
573.It Sy disctype
574This can have the following values:
575.Bl -tag -width cdromXdvdromXbdromXXX -compact
576.It Sy cdrom , Sy dvdrom , Sy bdrom
577create a read-only fs
578.It Sy dvdram , Sy bdre , Sy disk
579create a rewritable fs without sparing for defective sectors
580.It Sy cdr , Sy dvdr , Sy bdr
581create a rewritable fs on once recordable media using a VAT
582.It Sy cdrw , Sy dvdrw
583create a rewritable fs with sparing for defective sectors
584.El
585The sectorsize is set for the selected media and the default maximum disc size
586is assumed unless overridden.
587For CD-ROM, DVD-ROM and BD-ROM images, the disc
588size is the minimum size needed.
589Note that the size estimator can
590under-estimate in some cases; specify extra free blocks if encountering this.
591.It Sy loglabel
592Set the logical volume label of the disc to the specified argument.
593.It Sy discid
594Set the physical volume label of the disc to the specified argument.
595Prepend the physical volume label with a volumeset label separated
596with a ':' if wanted.
597For strict conformance and interchange, don't set the volumeset label
598manually unless it has an unique hex number in the first 8 character
599positions.
600.It Sy minver
601Set the minimum UDF version to be used.
602Choose UDF version numbers from 0x102, 0x150, 0x200, 0x201, and 0x250.
603Version 0x260 is currently not supported
604in
605.Nm .
606.It Sy maxver
607Set the maximum UDF version to be used.
608Choose UDF version numbers from 0x102, 0x150, 0x200, 0x201, and 0x250.
609Version 0x260 is currently not supported
610in
611.Nm .
612.It Sy metaperc
613Set the minimum amount of free metadata space.
614This is only applicable on UDF 0x250 on rewritable media.
615.It Sy checksurface
616Check the surface of non error-free rewritable media for remapping.
617Note this is a destructive test and can take quite a while!
618.It Sy forceformat
619Force formatting on non-empty recordable media.
620.El
621.Sh SEE ALSO
622.Xr strsuftoll 3 ,
623.Xr installboot 8 ,
624.Xr mtree 8 ,
625.Xr newfs 8
626.Sh HISTORY
627The
628.Nm
629utility appeared in
630.Nx 1.6 .
631.Sh AUTHORS
632.An Luke Mewburn
633.Aq lukem@NetBSD.org
634(original program),
635.An Daniel Watt ,
636.An Walter Deignan ,
637.An Ryan Gabrys ,
638.An Alan Perez-Rathke ,
639.An Ram Vedam
640(cd9660 support),
641.An UCHIYAMA Yasushi
642(v7fs support),
643.An Tamas Toth
644(chfs support),
645.An Christos Zoulas
646(msdos support),
647.An Reinoud Zandijk
648(udf support).