1erofs-utils 2=========== 3 4Userspace tools for EROFS filesystem, currently including: 5 6 mkfs.erofs filesystem formatter 7 erofsfuse FUSE daemon alternative 8 dump.erofs filesystem analyzer 9 fsck.erofs filesystem compatibility & consistency checker as well 10 as extractor 11 12 13EROFS filesystem overview 14------------------------- 15 16EROFS filesystem stands for Enhanced Read-Only File System. It aims to 17form a generic read-only filesystem solution for various read-only use 18cases instead of just focusing on storage space saving without 19considering any side effects of runtime performance. 20 21Typically EROFS could be considered in the following use scenarios: 22 - Firmwares in performance-sensitive systems, such as system 23 partitions of Android smartphones; 24 25 - Mountable immutable images such as container images for effective 26 metadata & data access compared with tar, cpio or other local 27 filesystems (e.g. ext4, XFS, btrfs, etc.) 28 29 - FSDAX-enabled rootfs for secure containers (Linux 5.15+); 30 31 - Live CDs which need a set of files with another high-performance 32 algorithm to optimize startup time; others files for archival 33 purposes only are not needed; 34 35 - and more. 36 37Note that all EROFS metadata is uncompressed by design, so that you 38could take EROFS as a drop-in read-only replacement of ext4, XFS, 39btrfs, etc. without any compression-based dependencies and EROFS can 40bring more effective filesystem accesses to users with reduced 41metadata. 42 43For more details of EROFS filesystem itself, please refer to: 44https://www.kernel.org/doc/html/next/filesystems/erofs.html 45 46For more details on how to build erofs-utils, see `docs/INSTALL.md`. 47 48For more details about filesystem performance, see 49`docs/PERFORMANCE.md`. 50 51 52mkfs.erofs 53---------- 54 55Two main kinds of EROFS images can be generated: (un)compressed images. 56 57 - For uncompressed images, there will be no compressed files in these 58 images. However, an EROFS image can contain files which consist of 59 various aligned data blocks and then a tail that is stored inline in 60 order to compact images [1]. 61 62 - For compressed images, it will try to use the given algorithms first 63 for each regular file and see if storage space can be saved with 64 compression. If not, it will fall back to an uncompressed file. 65 66Note that EROFS supports per-file compression configuration, proper 67configuration options need to be enabled to parse compressed files by 68the Linux kernel. 69 70How to generate EROFS images 71~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 72 73Compression algorithms could be specified with the command-line option 74`-z` to build a compressed EROFS image from a local directory: 75 $ mkfs.erofs -zlz4hc foo.erofs.img foo/ 76 77Supported algorithms by the Linux kernel: 78 - LZ4 (Linux 5.3+); 79 - LZMA (Linux 5.16+); 80 - DEFLATE (Linux 6.6+); 81 - Zstandard (Linux 6.10+). 82 83Alternatively, generate an uncompressed EROFS from a local directory: 84 $ mkfs.erofs foo.erofs.img foo/ 85 86Additionally, you can specify a higher compression level to get a 87(slightly) smaller image than the default level: 88 $ mkfs.erofs -zlz4hc,12 foo.erofs.img foo/ 89 90Multi-threaded support can be explicitly enabled with the ./configure 91option `--enable-multithreading`; otherwise, single-threaded compression 92will be used for now. It may take more time on multiprocessor platforms 93if multi-threaded support is not enabled. 94 95Currently, both `-Efragments` (not `-Eall-fragments`) and `-Ededupe` 96don't support multi-threading due to time limitations. 97 98Reproducible builds 99~~~~~~~~~~~~~~~~~~~ 100 101Reproducible builds are typically used for verification and security, 102ensuring the same binaries/distributions to be reproduced in a 103deterministic way. 104 105Images generated by the same version of `mkfs.erofs` will be identical 106to previous runs if the same input is specified, and the same options 107are used. 108 109Specifically, variable timestamps and filesystem UUIDs can result in 110unreproducible EROFS images. `-T` and `-U` can be used to fix them. 111 112How to generate EROFS big pcluster images (Linux 5.13+) 113~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 115By default, EROFS formatter compresses data into separate one-block 116(e.g. 4KiB) filesystem physical clusters for outstanding random read 117performance. In other words, each EROFS filesystem block can be 118independently decompressed. However, other similar filesystems 119typically compress data into "blocks" of 128KiB or more for much smaller 120images. Users may prefer smaller images for archiving purposes, even if 121random performance is compromised with those configurations, and even 122worse when using 4KiB blocks. 123 124In order to fulfill users' needs, big plusters has been introduced 125since Linux 5.13, in which each physical clusters will be more than one 126blocks. 127 128Specifically, `-C` is used to specify the maximum size of each pcluster 129in bytes: 130 $ mkfs.erofs -zlz4hc -C65536 foo.erofs.img foo/ 131 132Thus, in this case, pcluster sizes can be up to 64KiB. 133 134Note that large pcluster size can degrade random performance (though it 135may improve sequential read performance for typical storage devices), so 136please evaluate carefully in advance. Alternatively, you can make 137per-(sub)file compression strategies according to file access patterns 138if needed. 139 140How to generate EROFS images with multiple algorithms 141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 142 143It's possible to generate an EROFS image with files in different 144algorithms due to various purposes. For example, LZMA for archival 145purposes and LZ4 for runtime purposes. 146 147In order to use alternative algorithms, just specify two or more 148compressing configurations together separated by ':' like below: 149 -zlzma:lz4hc,12:lzma,9 -C32768 150 151Although mkfs still choose the first one by default, you could try to 152write a compress-hints file like below: 153 4096 1 .*\.so$ 154 32768 2 .*\.txt$ 155 4096 sbin/.*$ 156 16384 0 .* 157 158and specify with `--compress-hints=` so that ".so" files will use 159"lz4hc,12" compression with 4k pclusters, ".txt" files will use 160"lzma,9" compression with 32k pclusters, files under "/sbin" will use 161the default "lzma" compression with 4k plusters and other files will 162use "lzma" compression with 16k pclusters. 163 164Note that the largest pcluster size should be specified with the "-C" 165option (here 32k pcluster size), otherwise all larger pclusters will be 166limited. 167 168How to generate well-compressed EROFS images 169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 170 171Even if EROFS is not designed for such purposes in the beginning, it 172could still produce some smaller images (not always) compared to other 173approaches with better performance (see `docs/PERFORMANCE.md`). In 174order to build well-compressed EROFS images, try the following options: 175 -C1048576 (5.13+) 176 -Eztailpacking (5.16+) 177 -Efragments / -Eall-fragments ( 6.1+); 178 -Ededupe ( 6.1+). 179 180Also EROFS uses lz4hc level 9 by default, whereas some other approaches 181use lz4hc level 12 by default. So please explicitly specify 182`-zlz4hc,12 ` for comparison purposes. 183 184How to generate legacy EROFS images (Linux 4.19+) 185~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 186 187Decompression inplace and compacted indexes have been introduced in 188Linux v5.3, which are not forward-compatible with older kernels. 189 190In order to generate _legacy_ EROFS images for old kernels, 191consider adding "-E legacy-compress" to the command line, e.g. 192 193 $ mkfs.erofs -E legacy-compress -zlz4hc foo.erofs.img foo/ 194 195For Linux kernel >= 5.3, legacy EROFS images are _NOT recommended_ 196due to runtime performance loss compared with non-legacy images. 197 198Obsoleted erofs.mkfs 199~~~~~~~~~~~~~~~~~~~~ 200 201There is an original erofs.mkfs version developed by Li Guifu, 202which was replaced by the new erofs-utils implementation. 203 204git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git -b obsoleted_mkfs 205 206PLEASE NOTE: This version is highly _NOT recommended_ now. 207 208 209erofsfuse 210--------- 211 212erofsfuse is introduced to support EROFS format for various platforms 213(including older linux kernels) and new on-disk features iteration. 214It can also be used as an unpacking tool for unprivileged users. 215 216It supports fixed-sized output decompression *without* any in-place 217I/O or in-place decompression optimization. Also like the other FUSE 218implementations, it suffers from most common performance issues (e.g. 219significant I/O overhead, double caching, etc.) 220 221Therefore, NEVER use it if performance is the top concern. 222 223How to mount an EROFS image with erofsfuse 224~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 225 226As the other FUSE implementations, it's quite easy to mount by using 227erofsfuse, e.g.: 228 $ erofsfuse foo.erofs.img foo/ 229 230Alternatively, to make it run in foreground (with debugging level 3): 231 $ erofsfuse -f --dbglevel=3 foo.erofs.img foo/ 232 233To debug erofsfuse (also automatically run in foreground): 234 $ erofsfuse -d foo.erofs.img foo/ 235 236To unmount an erofsfuse mountpoint as a non-root user: 237 $ fusermount -u foo/ 238 239 240dump.erofs and fsck.erofs 241------------------------- 242 243dump.erofs and fsck.erofs are used to analyze, check, and extract 244EROFS filesystems. Note that extended attributes and ACLs are still 245unsupported when extracting images with fsck.erofs. 246 247Note that fragment extraction with fsck.erofs could be slow now and 248it needs to be optimized later. If you are interested, contribution 249is, as always, welcome. 250 251 252Contribution 253------------ 254 255erofs-utils is a part of EROFS filesystem project, which is completely 256community-driven open source software. If you have interest in EROFS, 257feel free to send feedback and/or patches to: 258 linux-erofs mailing list <[email protected]> 259 260 261Comments 262-------- 263 264[1] According to the EROFS on-disk format, the tail blocks of files 265 could be inlined aggressively with their metadata (called 266 tail-packing) in order to minimize the extra I/Os and the storage 267 space. 268