MKFS.EROFS(1)

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 SOURCE directory or tarball.

OPTIONS

-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.

-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 v5.13+).

-d #
    Specify the level of debugging messages. The default is 2, which shows basic warning messages.

-x #
    Limit how many xattrs will be inlined. The default is 2. 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:

    all-fragments
        Forcely record the whole files into a special inode for better compression and it may take an argument as the pcluster size of the packed inode in bytes. (Linux v6.1+)

    dedupe
        Enable global compressed data deduplication to minimize duplicated data in the filesystem. May further reduce image size when used with -E fragments. (Linux v6.1+)

    force-inode-compact
        Force generation of compact (32-byte) inodes.

    force-inode-extended
        Force generation of extended (64-byte) inodes.

    force-inode-blockmap
        Force generation of inode chunk format as a 4-byte block address array.

    force-chunk-indexes
        Forcely generate inode chunk format as an 8-byte chunk index (with device ID).

    [^]fragdedupe[=<inode|full>]
        Set the mode for fragment data deduplication. It's effective only when -E(all)-fragments is used together. If a caret ('^') character is set, fragment data deduplication is disabled.

        inode
            Deduplicate fragment data only when the inode data is identical. This option will result in faster image generation with the current codebase

        full
            Always deduplicate fragment data if possible

    fragments[=size]
        Pack the tail part (pcluster) of compressed files, or entire files, into a special inode for smaller image sizes, and it may take an argument as the pcluster size of the packed inode in bytes. (Linux v6.1+)

    ^inline_data
        Don't inline regular files. It's typically useful to enable FSDAX (Linux 5.15+) for those images, however, there could be other use cases too.

    legacy-compress
        Disable "inplace decompression" and "compacted indexes", for compatibility with Linux pre-v5.4.

    xattr-name-filter
        Enable a name filter for extended attributes to optimize negative lookups. (Linux v6.6+).

    ztailpacking
        Pack the tail part (pcluster) of compressed files into its metadata to save more space and the tail part I/O. (Linux v5.17+)

-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:

    clear
        clear the file system UUID

    random
        generate a new randomly-generated UUID

--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.

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

--chunksize #
    Generate chunk-based files with #-byte chunks.

--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:
    <pcluster-size-in-bytes> [algorithm-index] <match-pattern>
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 #.

--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.

-V, --version
    Print the version number and exit.

-h, --help
    Display help string and exit.

--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.

--max-extent-bytes #
    Specify maximum decompressed extent size in bytes.

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

--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.

--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. It can improve performance especially when SOURCE is not seekable.

--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.

--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 v6.4+).

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).