This allows one to take a staged directory tree and create a file consisting of a ZFS pool with one or more datasets that contain the contents of the directory tree. This is useful for creating virtual machine images without using the kernel to create a pool; "zpool create" requires root privileges and currently is not permitted in jails. makefs -t zfs also provides reproducible images by using a fixed seed for pseudo-random number generation, used for generating GUIDs and hash salts. makefs -t zfs requires relatively little by way of machine resources. The "zpool_reguid" rc.conf setting can be used to ask a FreeBSD guest to generate a unique pool GUID upon first boot. A small number of pool and dataset properties are supported. The pool is backed by a single disk vdev. Data is always checksummed using Fletcher-4, no redundant copies are made, and no compression is used. The manual page documents supported pool and filesystem properties. The implementation uses a few pieces of ZFS support from with the boot loader, especially definitions for various on-disk structures, but is otherwise standalone and in particular doesn't depend on OpenZFS. This feature should be treated as experimental for now, i.e., important data shouldn't be trusted to a makefs-created pool, and the command-line interface is subject to change. Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D35248
613 lines
16 KiB
Groff
613 lines
16 KiB
Groff
.\" $NetBSD: makefs.8,v 1.33 2011/05/22 21:51:39 christos Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001-2003 Wasabi Systems, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Written by Luke Mewburn for Wasabi Systems, Inc.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed for the NetBSD Project by
|
|
.\" Wasabi Systems, Inc.
|
|
.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
|
|
.\" or promote products derived from this software without specific prior
|
|
.\" written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 5, 2022
|
|
.Dt MAKEFS 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm makefs
|
|
.Nd create a file system image from a directory tree or a mtree manifest
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl DxZ
|
|
.Op Fl B Ar endian
|
|
.Op Fl b Ar free-blocks
|
|
.Op Fl d Ar debug-mask
|
|
.Op Fl F Ar mtree-specfile
|
|
.Op Fl f Ar free-files
|
|
.Op Fl M Ar minimum-size
|
|
.Op Fl m Ar maximum-size
|
|
.Op Fl N Ar userdb-dir
|
|
.Op Fl O Ar offset
|
|
.Op Fl o Ar fs-options
|
|
.Op Fl R Ar roundup-size
|
|
.Op Fl S Ar sector-size
|
|
.Op Fl s Ar image-size
|
|
.Op Fl T Ar timestamp
|
|
.Op Fl t Ar fs-type
|
|
.Ar image-file
|
|
.Ar directory | manifest
|
|
.Op Ar extra-directory ...
|
|
.Sh DESCRIPTION
|
|
The utility
|
|
.Nm
|
|
creates a file system image into
|
|
.Ar image-file
|
|
from the directory tree
|
|
.Ar directory
|
|
or from the mtree manifest
|
|
.Ar manifest .
|
|
If any optional directory trees are passed in the
|
|
.Ar extra-directory
|
|
arguments, then the directory tree of each argument will be merged
|
|
into the
|
|
.Ar directory
|
|
or
|
|
.Ar manifest
|
|
first before creating
|
|
.Ar image-file .
|
|
No special devices or privileges are required to perform this task.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width flag
|
|
.It Fl B Ar endian
|
|
Set the byte order of the image to
|
|
.Ar endian .
|
|
Valid byte orders are
|
|
.Ql 4321 ,
|
|
.Ql big ,
|
|
or
|
|
.Ql be
|
|
for big endian, and
|
|
.Ql 1234 ,
|
|
.Ql little ,
|
|
or
|
|
.Ql le
|
|
for little endian.
|
|
Some file systems may have a fixed byte order; in those cases this
|
|
argument will be ignored.
|
|
.It Fl b Ar free-blocks
|
|
Ensure that a minimum of
|
|
.Ar free-blocks
|
|
free blocks exist in the image.
|
|
An optional
|
|
.Ql %
|
|
suffix may be provided to indicate that
|
|
.Ar free-blocks
|
|
indicates a percentage of the calculated image size.
|
|
.It Fl D
|
|
Treat duplicate paths in an mtree manifest as warnings not error.
|
|
.It Fl d Ar debug-mask
|
|
Enable various levels of debugging, depending upon which bits are
|
|
set in
|
|
.Ar debug-mask .
|
|
XXX: document these
|
|
.It Fl F Ar mtree-specfile
|
|
.Em This is almost certainly not the option you are looking for.
|
|
To create an image from a list of files in an mtree format manifest,
|
|
specify it as the last argument on the command line, not as a the
|
|
argument to
|
|
.Fl F .
|
|
.Pp
|
|
Use
|
|
.Ar mtree-specfile
|
|
as an
|
|
.Xr mtree 8
|
|
.Sq specfile
|
|
specification.
|
|
This option has no effect when the image is created from a mtree manifest
|
|
rather than a directory.
|
|
.Pp
|
|
If a specfile entry exists in the underlying file system, its
|
|
permissions and modification time will be used unless specifically
|
|
overridden by the specfile.
|
|
An error will be raised if the type of entry in the specfile
|
|
conflicts with that of an existing entry.
|
|
.Pp
|
|
In the opposite case (where a specfile entry does not have an entry
|
|
in the underlying file system) the following occurs:
|
|
If the specfile entry is marked
|
|
.Sy optional ,
|
|
the specfile entry is ignored.
|
|
Otherwise, the entry will be created in the image, and it is
|
|
necessary to specify at least the following parameters in the
|
|
specfile:
|
|
.Sy type ,
|
|
.Sy mode ,
|
|
.Sy gname ,
|
|
or
|
|
.Sy gid ,
|
|
and
|
|
.Sy uname
|
|
or
|
|
.Sy uid ,
|
|
and
|
|
.Sy link
|
|
(in the case of symbolic links).
|
|
If
|
|
.Sy time
|
|
is not provided, the current time will be used.
|
|
If
|
|
.Sy flags
|
|
is not provided, the current file flags will be used.
|
|
Missing regular file entries will be created as zero-length files.
|
|
.It Fl f Ar free-files
|
|
Ensure that a minimum of
|
|
.Ar free-files
|
|
free files (inodes) exist in the image.
|
|
An optional
|
|
.Ql %
|
|
suffix may be provided to indicate that
|
|
.Ar free-files
|
|
indicates a percentage of the calculated image size.
|
|
.It Fl M Ar minimum-size
|
|
Set the minimum size of the file system image to
|
|
.Ar minimum-size .
|
|
.It Fl m Ar maximum-size
|
|
Set the maximum size of the file system image to
|
|
.Ar maximum-size .
|
|
An error will be raised if the target file system needs to be larger
|
|
than this to accommodate the provided directory tree.
|
|
.It Fl N Ar userdb-dir
|
|
Use the user database text file
|
|
.Pa master.passwd
|
|
and group database text file
|
|
.Pa group
|
|
from
|
|
.Ar userdb-dir ,
|
|
rather than using the results from the system's
|
|
.Xr getpwnam 3
|
|
and
|
|
.Xr getgrnam 3
|
|
(and related) library calls.
|
|
.It Fl O Ar offset
|
|
Instead of creating the filesystem at the beginning of the file, start
|
|
at offset.
|
|
Valid only for
|
|
.Sy ffs
|
|
and
|
|
.Sy msdos .
|
|
.It Fl o Ar fs-options
|
|
Set file system specific options.
|
|
.Ar fs-options
|
|
is a comma separated list of options.
|
|
Valid file system specific options are detailed below.
|
|
.It Fl p
|
|
Deprecated.
|
|
See the
|
|
.Fl Z
|
|
flag.
|
|
.It Fl R Ar roundup-size
|
|
Round the image up to
|
|
.Ar roundup-size .
|
|
.Ar roundup-size
|
|
should be a multiple of the file system block size.
|
|
This option only applies to the
|
|
.Sy ffs
|
|
file system type.
|
|
.It Fl S Ar sector-size
|
|
Set the file system sector size to
|
|
.Ar sector-size .
|
|
.\" XXX: next line also true for cd9660?
|
|
Defaults to 512.
|
|
.It Fl s Ar image-size
|
|
Set the size of the file system image to
|
|
.Ar image-size .
|
|
This is equivalent to setting both the minimum
|
|
.Fl ( M )
|
|
and the maximum
|
|
.Fl ( m )
|
|
sizes to the same value.
|
|
For
|
|
.Sy ffs
|
|
and
|
|
.Sy msdos
|
|
the
|
|
.Ar image-size
|
|
does not include the
|
|
.Ar offset .
|
|
.Ar offset
|
|
is not included in that size.
|
|
.It Fl T Ar timestamp
|
|
Specify a timestamp to be set for all filesystem files and directories
|
|
created so that repeatable builds are possible.
|
|
The
|
|
.Ar timestamp
|
|
can be a
|
|
.Pa pathname ,
|
|
where the timestamps are derived from that file, or an integer
|
|
value interpreted as the number of seconds from the Epoch.
|
|
Note that timestamps specified in an
|
|
.Xr mtree 5
|
|
spec file, override the default timestamp.
|
|
.It Fl t Ar fs-type
|
|
Create an
|
|
.Ar fs-type
|
|
file system image.
|
|
The following file system types are supported:
|
|
.Bl -tag -width cd9660 -offset indent
|
|
.It Sy ffs
|
|
BSD fast file system (default).
|
|
.It Sy cd9660
|
|
ISO 9660 file system.
|
|
.It Sy msdos
|
|
FAT12, FAT16, or FAT32 file system.
|
|
.It Sy zfs
|
|
ZFS pool containing one or more file systems.
|
|
.El
|
|
.It Fl x
|
|
Exclude file system nodes not explicitly listed in the specfile.
|
|
.It Fl Z
|
|
Create a sparse file for
|
|
.Sy ffs .
|
|
This is useful for virtual machine images.
|
|
.El
|
|
.Pp
|
|
Where sizes are specified, a decimal number of bytes is expected.
|
|
Two or more numbers may be separated by an
|
|
.Dq x
|
|
to indicate a product.
|
|
Each number may have one of the following optional suffixes:
|
|
.Bl -tag -width 3n -offset indent -compact
|
|
.It b
|
|
Block; multiply by 512
|
|
.It k
|
|
Kibi; multiply by 1024 (1 KiB)
|
|
.It m
|
|
Mebi; multiply by 1048576 (1 MiB)
|
|
.It g
|
|
Gibi; multiply by 1073741824 (1 GiB)
|
|
.It t
|
|
Tebi; multiply by 1099511627776 (1 TiB)
|
|
.It w
|
|
Word; multiply by the number of bytes in an integer
|
|
.El
|
|
.\"
|
|
.\"
|
|
.Ss FFS-specific options
|
|
.Sy ffs
|
|
images have ffs-specific optional parameters that may be provided.
|
|
Each of the options consists of a keyword, an equal sign
|
|
.Pq Ql = ,
|
|
and a value.
|
|
The following keywords are supported:
|
|
.Pp
|
|
.Bl -tag -width optimization -offset indent -compact
|
|
.It Sy avgfilesize
|
|
Expected average file size.
|
|
.It Sy avgfpdir
|
|
Expected number of files per directory.
|
|
.It Sy bsize
|
|
Block size.
|
|
.It Sy density
|
|
Bytes per inode. If unset, will allocate the minimum number of inodes to
|
|
represent the filesystem if no free space has been requested (free blocks
|
|
or minimum size set); otherwise the larger of the newfs defaults or what
|
|
is required by the free inode parameters if set.
|
|
.It Sy fsize
|
|
Fragment size.
|
|
.It Sy label
|
|
Label name of the image.
|
|
.It Sy maxbpg
|
|
Maximum blocks per file in a cylinder group.
|
|
.It Sy minfree
|
|
Minimum % free.
|
|
.It Sy optimization
|
|
Optimization preference; one of
|
|
.Ql space
|
|
or
|
|
.Ql time .
|
|
.It Sy extent
|
|
Maximum extent size.
|
|
.It Sy maxbpcg
|
|
Maximum total number of blocks in a cylinder group.
|
|
.It Sy version
|
|
UFS version.
|
|
1 for FFS (default), 2 for UFS2.
|
|
.It Sy softupdates
|
|
0 for disable (default), 1 for enable
|
|
.El
|
|
.Ss CD9660-specific options
|
|
.Sy cd9660
|
|
images have ISO9660-specific optional parameters that may be
|
|
provided.
|
|
The arguments consist of a keyword and, optionally, an equal sign
|
|
.Pq Ql = ,
|
|
and a value.
|
|
The following keywords are supported:
|
|
.Pp
|
|
.Bl -tag -width omit-trailing-period -offset indent -compact
|
|
.It Sy allow-deep-trees
|
|
Allow the directory structure to exceed the maximum specified in
|
|
the spec.
|
|
.It Sy allow-illegal-chars
|
|
Allow illegal characters in filenames.
|
|
This option is not implemented.
|
|
.It Sy allow-lowercase
|
|
Allow lowercase characters in filenames.
|
|
This option is not implemented.
|
|
.It Sy allow-max-name
|
|
Allow 37 instead of 33 characters for filenames by omitting the
|
|
version id.
|
|
.It Sy allow-multidot
|
|
Allow multiple dots in a filename.
|
|
.It Sy applicationid
|
|
Application ID of the image.
|
|
.It Sy archimedes
|
|
Use the
|
|
.Ql ARCHIMEDES
|
|
extension to encode
|
|
.Tn RISC OS
|
|
metadata.
|
|
.It Sy bootimagedir
|
|
Boot image directory.
|
|
This option is not implemented.
|
|
.It Sy chrp-boot
|
|
Write an MBR partition table to the image to allow older CHRP hardware to
|
|
boot.
|
|
.It Sy boot-load-segment
|
|
Set load segment for the boot image.
|
|
.It Sy bootimage
|
|
Filename of a boot image in the format
|
|
.Dq sysid;filename ,
|
|
where
|
|
.Dq sysid
|
|
is one of
|
|
.Ql efi ,
|
|
.Ql i386 ,
|
|
.Ql mac68k ,
|
|
.Ql macppc ,
|
|
or
|
|
.Ql powerpc .
|
|
.It Sy generic-bootimage
|
|
Load a generic boot image into the first 32K of the cd9660 image.
|
|
.It Sy hard-disk-boot
|
|
Boot image is a hard disk image.
|
|
.It Sy isolevel
|
|
An integer representing the ISO 9660 interchange level where
|
|
.Dq level
|
|
is either
|
|
.Ql 1
|
|
or
|
|
.Ql 2 .
|
|
.Dq level
|
|
.Ql 3
|
|
is not implemented.
|
|
.It Sy keep-bad-images
|
|
Do not discard images whose write was aborted due to an error.
|
|
For debugging purposes.
|
|
.It Sy label
|
|
Label name of the image.
|
|
.It Sy no-boot
|
|
Boot image is not bootable.
|
|
.It Sy no-emul-boot
|
|
Boot image is a
|
|
.Dq no emulation
|
|
ElTorito image.
|
|
.It Sy no-trailing-padding
|
|
Do not pad the image (apparently Linux needs the padding).
|
|
.It Sy omit-trailing-period
|
|
Omit trailing periods in filenames.
|
|
.It Sy platformid
|
|
Set platform ID of section header entry of the boot image.
|
|
.It Sy preparer
|
|
Preparer ID of the image.
|
|
.It Sy publisher
|
|
Publisher ID of the image.
|
|
.It Sy rockridge
|
|
Use RockRidge extensions (for longer filenames, etc.).
|
|
.It Sy verbose
|
|
Turns on verbose output.
|
|
.It Sy volumeid
|
|
Volume set identifier of the image.
|
|
.El
|
|
.Ss msdos-specific options
|
|
.Sy msdos
|
|
images have MS-DOS-specific optional parameters that may be
|
|
provided.
|
|
The arguments consist of a keyword, an equal sign
|
|
.Pq Ql = ,
|
|
and a value.
|
|
The following keywords are supported (see
|
|
.Xr newfs_msdos 8
|
|
for more details):
|
|
.Pp
|
|
.Bl -tag -width omit-trailing-period -offset indent -compact
|
|
.It Cm backup_sector
|
|
Location of the backup boot sector.
|
|
.It Cm block_size
|
|
Block size.
|
|
.It Cm bootstrap
|
|
Bootstrap file.
|
|
.It Cm bytes_per_sector
|
|
Bytes per sector.
|
|
.It Cm create_size
|
|
Create file size.
|
|
.It Cm directory_entries
|
|
Directory entries.
|
|
.It Cm drive_heads
|
|
Drive heads.
|
|
.It Cm fat_type
|
|
FAT type (12, 16, or 32).
|
|
.It Cm floppy
|
|
Preset drive parameters for standard format floppy disks
|
|
(160, 180, 320, 360, 640, 720, 1200, 1232, 1440, or 2880).
|
|
.It Cm hidden_sectors
|
|
Hidden sectors.
|
|
.It Cm info_sector
|
|
Location of the info sector.
|
|
.It Cm media_descriptor
|
|
Media descriptor.
|
|
.It Cm num_FAT
|
|
Number of FATs.
|
|
.It Cm OEM_string
|
|
OEM string.
|
|
.It Cm offset
|
|
Offset in device.
|
|
This option will be ignored if
|
|
.Fl O
|
|
is set to a positive number.
|
|
.It Cm reserved_sectors
|
|
Reserved sectors.
|
|
.It Cm sectors_per_cluster
|
|
Sectors per cluster.
|
|
.It Cm sectors_per_fat
|
|
Sectors per FAT.
|
|
.It Cm sectors_per_track
|
|
Sectors per track.
|
|
.It Cm size
|
|
File System size.
|
|
.It Cm volume_id
|
|
Volume ID.
|
|
.It Cm volume_label
|
|
Volume Label.
|
|
.El
|
|
.Ss zfs-specific options
|
|
Note: ZFS support is currently considered experimental.
|
|
Do not use it for anything critical.
|
|
.Pp
|
|
The image created by
|
|
.Nm
|
|
contains a ZFS pool with a single vdev of type
|
|
.Ql disk .
|
|
The root dataset is always created implicitly and contains the entire input
|
|
directory tree unless additional datasets are specified using the options
|
|
described below.
|
|
.Pp
|
|
The arguments consist of a keyword, an equal sign
|
|
.Pq Ql = ,
|
|
and a value.
|
|
The following keywords are supported:
|
|
.Pp
|
|
.Bl -tag -width omit-trailing-period -offset indent -compact
|
|
.It ashift
|
|
The base-2 logarithm of the minimum block size.
|
|
Typical values are 9 (512B blocks) and 12 (4KB blocks).
|
|
The default value is 12.
|
|
.It bootfs
|
|
The name of the bootable dataset for the pool.
|
|
Specifying this option causes the
|
|
.Ql bootfs
|
|
property to be set in the created pool.
|
|
.It mssize
|
|
The size of metaslabs in the created pool.
|
|
By default,
|
|
.Nm
|
|
allocates large (up to 512MB) metaslabs with the expectation that
|
|
the image will be auto-expanded upon first use.
|
|
This option allows the default heuristic to be overridden.
|
|
.It poolname
|
|
The name of the ZFS pool.
|
|
This option must be specified.
|
|
.It rootpath
|
|
An implicit path prefix added to dataset mountpoints.
|
|
By default it is
|
|
.Pa /<poolname> .
|
|
For creating bootable pools, the
|
|
.Va rootpath
|
|
should be set to
|
|
.Pa / .
|
|
At least one dataset must have a mountpoint equal to
|
|
.Va rootpath .
|
|
.It fs
|
|
Create an additional dataset.
|
|
This option may be specified multiple times.
|
|
The argument value must be of the form
|
|
.Ar <dataset>[;<prop1=v1>[;<prop2=v2>[;...]]] ,
|
|
where
|
|
.Ar dataset
|
|
is the name of the dataset and must belong to the pool's namespace.
|
|
For example, with a pool name of
|
|
.Ql test
|
|
all dataset names must be prefixed by
|
|
.Ql test/ .
|
|
A dataset must exist at each level of the pool's namespace.
|
|
For example, to create
|
|
.Ql test/foo/bar ,
|
|
.Ql test/foo
|
|
must be created as well.
|
|
.Pp
|
|
The dataset mountpoints determine how the datasets are populated with
|
|
files from the staged directory tree.
|
|
Conceptually, all datasets are mounted before any are populated with files.
|
|
The root of the staged directory tree is mapped to
|
|
.Va rootpath .
|
|
.Pp
|
|
Dataset properties, as described in
|
|
.Xr zfsprops 8 ,
|
|
may be specified following the dataset name.
|
|
The following properties may be set for a dataset:
|
|
.Pp
|
|
.Bl -tag -compact -offset indent
|
|
.It atime
|
|
.It canmount
|
|
.It exec
|
|
.It mountpoint
|
|
.It setuid
|
|
.El
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr mtree 5 ,
|
|
.Xr mtree 8 ,
|
|
.Xr newfs 8 ,
|
|
.Xr zfsconcepts 8 ,
|
|
.Xr zfsprops 8 ,
|
|
.Xr zpoolprops 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Nx 1.6 .
|
|
It was ported to
|
|
.Fx
|
|
and first appeared in
|
|
.Fx 8.0 .
|
|
.Sh AUTHORS
|
|
.An Luke Mewburn
|
|
.Aq Mt lukem@NetBSD.org
|
|
(original program),
|
|
.An Daniel Watt ,
|
|
.An Walter Deignan ,
|
|
.An Ryan Gabrys ,
|
|
.An Alan Perez-Rathke ,
|
|
.An Ram Vedam
|
|
(cd9660 support),
|
|
.An Christos Zoulas
|
|
(msdos support),
|
|
.An Mark Johnston
|
|
(zfs support).
|