NAME

mkfs.erofs - tool to create an EROFS filesystem

SYNOPSIS

mkfs.erofs [OPTIONS] DESTINATION SOURCE

DESCRIPTION

EROFS is a new enhanced lightweight linux read-only filesystem with modern designs (eg. no buffer head, reduced metadata, inline xattrs/data, etc.) for scenarios which need high-performance read-only requirements, e.g. Android OS for smartphones and LIVECDs.

It also provides fixed-sized output compression support, which improves storage density, keeps relatively higher compression ratios, which is more useful to achieve high performance for embedded devices with limited memory since it has unnoticable memory overhead and page cache thrashing.

mkfs.erofs is used to create such EROFS filesystem DESTINATION image file from various SOURCE, where SOURCE can be:

OPTIONS

-b block-size

Set the fundamental block size of the filesystem in bytes. In other words, specify the smallest amount of data that can be accessed at a time. The default is the system page size. It cannot be less than 512 bytes.

-C max-pcluster-size

Specify the maximum size of compress physical cluster in bytes. This may cause the big pcluster feature to be enabled (Linux 5.13+).

-m #[:compression-algorithm]

Enable metadata compression with #-byte clusters in a metabox inode (Linux 6.17+); optionally specify a compression algorithm (defaults to data compression algorithm if omitted).

--MZ[=<0|[id]>]

Put inode metadata ('i') and/or directory data ('d') into the separate metadata zone. This improves spatial locality of metadata layout within the image, which is beneficial for metadata access if the storage has long I/O latencies.

-x #

Limit how many xattrs will be inlined. The default is 2.

-z compression-algorithm[,#][:...]

Set a primary algorithm for data compression, which can be set with an optional compression level. Alternative algorithms could be specified and separated by colons. See the output of mkfs.erofs --help for a listing of the algorithms that mkfs.erofs is compiled with and what their respective level ranges are.

--zD[=<0|1>]

Used to enable directory compression: 0=disable, 1=enable. If the optional argument is omitted, directory compression is enabled by default.

-d #

Specify the level of debugging messages. The default is 2, which shows basic warning messages. Disables storing xattrs if < 0.

-E [^]extended-option[,...]

Set extended options for the filesystem. Extended options are comma separated, and may take an extra argument using the equals ('=') sign. To disable a feature, usually prefix the extended option name with a caret ('^') character. The following extended options are supported:

-L volume-label

Set the volume label for the filesystem to volume-label. The maximum length of the volume label is 15 bytes.

-T #

Specify a UNIX timestamp for image creation time for reproducible builds. If --mkfs-time is not specified, it will behave as --all-time: setting all files to the specified UNIX timestamp instead of using the modification times of the source files.

-U UUID

Set the universally unique identifier (UUID) of the filesystem to UUID. The format of the UUID is a series of hex digits separated by hyphens, like this: "c1b9d5a2-f162-11cf-9ece-0020afc76f16". The UUID parameter may also be one of the following:

--all-root

Make all files owned by root.

--all-time

(used together with -T) set all files to the fixed timestamp. This is the default.

--async-queue-limit=#

Specify the maximum number of entries in the multi-threaded job queue.

--aufs

Replace aufs special files with overlayfs metadata.

--blobdev file

Specify an extra blob device to store chunk-based data.

--chunksize #

Generate chunk-based files with #-byte chunks.

--clean=MODE

Run full clean build with the given MODE, which could be one of data, rvsp, or 0.

If --clean is specified without an explicit value, it is treated as --clean=data.

data: Import complete file data from the source into the destination image, creating a fully self-contained EROFS image. This mode is useful when you need a standalone image that doesn't depend on external blob devices.

rvsp: Reserve space for file data in the destination image without copying the actual content. The file data will need to be filled in later through other means. This is useful for creating sparse images or when the actual data will be populated separately.

0:Fill all inode data with zeros.

The current source-specific support for MODE:

--compress-hints=file

Apply a per-file compression strategy. Each line in file is defined by tokens separated by spaces in the following form. Optionally, instead of the given primary algorithm, alternative algorithms can be specified with algorithm-index explicitly:

match-patterns are extended regular expressions, matched against absolute paths within the output filesystem, with no leading /.

--dsunit=#

Align all data block addresses to multiples of #.

If --dsunit and --chunksize are both set, --dsunit will be ignored if it is larger than --chunksize.

If --dsunit is larger, it spans multiple chunks, for example: -b 4096, --dsunit 512 (2MiB), --chunksize 4096

Once a chunk is deduplicated, all subsequent chunks will no longer be aligned. For optimal performance, it is recommended to set --dsunit to the same value as --chunksize:

E.g. -b 4096, --dsunit 512 (2MiB), --chunksize $((4096*512))

--exclude-path=path

Ignore file that matches the exact literal path. You may give multiple --exclude-path options.

--exclude-regex=regex

Ignore files that match the given extended regular expression. You may give multiple --exclude-regex options.

--file-contexts=file

Read SELinux label configuration/overrides from file in the selinux_file(5) format.

--force-uid=UID

Set all file UIDs to UID.

--force-gid=GID

Set all file GIDs to GID.

--fsalignblks=#

Specify the alignment of the primary device size (usually the filesystem size) in blocks.

--gid-offset=GIDOFFSET

Add GIDOFFSET to all file GIDs. When this option is used together with --force-gid, the final file gids are set to GID + GID-OFFSET.

--gzinfo[=file]

(used together with --tar) Generate AWS SOCI-compatible zinfo to support random gzip access. Source file must be a gzip-compressed tarball.

--hard-dereference

Dereference hardlinks and add links as separate inodes.

--ignore-mtime

Ignore the file modification time whenever it would cause mkfs.erofs to use extended inodes over compact inodes. When not using a fixed timestamp, this can reduce total metadata size. Implied by -E force-inode-compact.

--incremental=MODE

Run an incremental build where DESTINATION is an existing EROFS image, and the data specified by SOURCE will be incrementally appended to the image. MODE has the same meaning as in --clean above. Incremental build is unsupported for --s3 and --oci sources.

If --incremental is specified without an explicit value, it is treated as --incremental=data.

The current source-specific support for MODE:

--max-extent-bytes=#

Specify maximum decompressed extent size in bytes. The default is unlimited.

--mkfs-time

(used together with -T) the given timestamp is only applied to the build time.

--mount-point=path

Specify the prefix of target filesystem path (default: /).

--oci[=<f|i>]

Generate a full (f) or index-only (i) image from OCI remote source. Additional options can be specified:

--offset=#

Skip # bytes at the beginning of the image.

--ovlfs-strip[=<0|1>]

Strip overlayfs metadata in the target image (e.g. whiteouts).

--preserve-mtime

Use extended inodes instead of compact inodes if the file modification time would overflow compact inodes. This is the default. Overrides --ignore-mtime.

--quiet

Quiet execution (do not write anything to standard output.)

--root-xattr-isize=#

Ensure the inline xattr size of the root directory is # bytes at least.

--s3=endpoint

Generate an image from S3-compatible object store. Additional options can be specified:

--sort=MODE

Inode data sorting order for tarballs as input.

MODE may be one of none or path.

none: No particular data order is specified for the target image to avoid unnecessary overhead; Currently, it takes effect if `-E^inline_data` is specified and no compression is applied.

path: Data order strictly follows the tree generation order. (default)

--tar, --tar=MODE

Treat SOURCE as a tarball or tarball-like "headerball" rather than as a directory.

MODE may be one of f, i, or headerball.

f: Generate a full EROFS image from a regular tarball. (default)

i: Generate a meta-only EROFS image from a regular tarball. Only metadata such as dentries, inodes, and xattrs will be added to the image, without file data. Uses for such images include as a layer in an overlay filesystem with other data-only layers.

headerball: Generate a meta-only EROFS image from a stream identical to a tarball except that file data is not present after each file header.

--uid-offset=UIDOFFSET

Add UIDOFFSET to all file UIDs. When this option is used together with --force-uid, the final file uids are set to UID + UIDOFFSET.

--ungzip[=file]

Filter tarball streams through gzip. Optionally, raw streams can be dumped together.

--unxz[=file]

Filter tarball streams through xz, lzma, or lzip. Optionally, raw streams can be dumped together.

--vmdk-desc=FILE

Generate a VMDK descriptor file to merge sub-filesystems, which can be used for tar index or rebuild mode.

--workers=#

Set the number of worker threads to # (default: number of CPUs).

--xattr-inode-digest=name

Specify extended attribute name to record inode digests.

--xattr-prefix=PREFIX

Specify a customized extended attribute namespace prefix for space saving, e.g. "trusted.overlay.". You may give multiple --xattr-prefix options (Linux 6.4+).

--zfeature-bits=#

Toggle filesystem compression features according to given bits #. Each bit in the value corresponds to a specific compression feature:

  7 6 5 4 3 2 1 0  (bit position)


  | | | | | | | |


  | | | | | | | +-- Bit 0 (1)   : legacy-compress


  | | | | | | +---- Bit 1 (2)   : ztailpacking


  | | | | | +------ Bit 2 (4)   : fragments


  | | | | +-------- Bit 3 (8)   : all-fragments


  | | | +---------- Bit 4 (16)  : dedupe


  | | +------------ Bit 5 (32)  : fragdedupe


  | +-------------- Bit 6 (64)  : 48bit


  +---------------- Bit 7 (128) : dot-omitted

For example, --zfeature-bits=6 (binary: 0000 0110) enables ztailpacking (bit 1) and fragments (bit 2).

-h, --help

Display help string and exit.

-V, --version

Print the version number and exit.

NOTES

REBUILD MODE

Rebuild mode allows mkfs.erofs to generate a new EROFS image from one or more existing EROFS images passed as SOURCE(s). This mode is particularly useful for merging multiple EROFS images or creating index-only metadata images that reference data in the source images.

When SOURCE contains one or more EROFS image files, mkfs.erofs automatically enters rebuild mode. The behavior is controlled by the --clean or --incremental options, which determine how file data is handled:

AUTHOR

This version of mkfs.erofs is written by Li Guifu <blucerlee@gmail.com>, Miao Xie <miaoxie@huawei.com> and Gao Xiang <xiang@kernel.org> with continuously improvements from others.

This manual page was written by Gao Xiang <xiang@kernel.org>.

AVAILABILITY

mkfs.erofs is part of erofs-utils package and is available from git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git.

SEE ALSO

mkfs(8).