Ubuntu Manpage: mkfs.erofs - tool to create an EROFS filesystem

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

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

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

noinline_data
Don't inline regular files to enable FSDAX for these files (Linux
v5.15+).

^xattr-name-filter
Turn off/on xattr name filter to optimize negative xattr 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 16 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".

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

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

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

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