1.. SPDX-License-Identifier: GPL-2.0 2 3======================= 4Squashfs 4.0 Filesystem 5======================= 6 7Squashfs is a compressed read-only filesystem for Linux. 8 9It uses zlib, lz4, lzo, or xz compression to compress files, inodes and 10directories. Inodes in the system are very small and all blocks are packed to 11minimise data overhead. Block sizes greater than 4K are supported up to a 12maximum of 1Mbytes (default block size 128K). 13 14Squashfs is intended for general read-only filesystem use, for archival 15use (i.e. in cases where a .tar.gz file may be used), and in constrained 16block device/memory systems (e.g. embedded systems) where low overhead is 17needed. 18 19Mailing list: squashfs-devel@lists.sourceforge.net 20Web site: www.squashfs.org 21 221. Filesystem Features 23---------------------- 24 25Squashfs filesystem features versus Cramfs: 26 27============================== ========= ========== 28 Squashfs Cramfs 29============================== ========= ========== 30Max filesystem size 2^64 256 MiB 31Max file size ~ 2 TiB 16 MiB 32Max files unlimited unlimited 33Max directories unlimited unlimited 34Max entries per directory unlimited unlimited 35Max block size 1 MiB 4 KiB 36Metadata compression yes no 37Directory indexes yes no 38Sparse file support yes no 39Tail-end packing (fragments) yes no 40Exportable (NFS etc.) yes no 41Hard link support yes no 42"." and ".." in readdir yes no 43Real inode numbers yes no 4432-bit uids/gids yes no 45File creation time yes no 46Xattr support yes no 47ACL support no no 48============================== ========= ========== 49 50Squashfs compresses data, inodes and directories. In addition, inode and 51directory data are highly compacted, and packed on byte boundaries. Each 52compressed inode is on average 8 bytes in length (the exact length varies on 53file type, i.e. regular file, directory, symbolic link, and block/char device 54inodes have different sizes). 55 562. Using Squashfs 57----------------- 58 59As squashfs is a read-only filesystem, the mksquashfs program must be used to 60create populated squashfs filesystems. This and other squashfs utilities 61can be obtained from http://www.squashfs.org. Usage instructions can be 62obtained from this site also. 63 64The squashfs-tools development tree is now located on kernel.org 65 git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git 66 672.1 Mount options 68----------------- 69=================== ========================================================= 70errors=%s Specify whether squashfs errors trigger a kernel panic 71 or not 72 73 ========== ============================================= 74 continue errors don't trigger a panic (default) 75 panic trigger a panic when errors are encountered, 76 similar to several other filesystems (e.g. 77 btrfs, ext4, f2fs, GFS2, jfs, ntfs, ubifs) 78 79 This allows a kernel dump to be saved, 80 useful for analyzing and debugging the 81 corruption. 82 ========== ============================================= 83threads=%s Select the decompression mode or the number of threads 84 85 If SQUASHFS_CHOICE_DECOMP_BY_MOUNT is set: 86 87 ========== ============================================= 88 single use single-threaded decompression (default) 89 90 Only one block (data or metadata) can be 91 decompressed at any one time. This limits 92 CPU and memory usage to a minimum, but it 93 also gives poor performance on parallel I/O 94 workloads when using multiple CPU machines 95 due to waiting on decompressor availability. 96 multi use up to two parallel decompressors per core 97 98 If you have a parallel I/O workload and your 99 system has enough memory, using this option 100 may improve overall I/O performance. It 101 dynamically allocates decompressors on a 102 demand basis. 103 percpu use a maximum of one decompressor per core 104 105 It uses percpu variables to ensure 106 decompression is load-balanced across the 107 cores. 108 1|2|3|... configure the number of threads used for 109 decompression 110 111 The upper limit is num_online_cpus() * 2. 112 ========== ============================================= 113 114 If SQUASHFS_CHOICE_DECOMP_BY_MOUNT is **not** set and 115 SQUASHFS_DECOMP_MULTI, SQUASHFS_MOUNT_DECOMP_THREADS are 116 both set: 117 118 ========== ============================================= 119 2|3|... configure the number of threads used for 120 decompression 121 122 The upper limit is num_online_cpus() * 2. 123 ========== ============================================= 124 125=================== ========================================================= 126 1273. Squashfs Filesystem Design 128----------------------------- 129 130A squashfs filesystem consists of a maximum of nine parts, packed together on a 131byte alignment:: 132 133 --------------- 134 | superblock | 135 |---------------| 136 | compression | 137 | options | 138 |---------------| 139 | datablocks | 140 | & fragments | 141 |---------------| 142 | inode table | 143 |---------------| 144 | directory | 145 | table | 146 |---------------| 147 | fragment | 148 | table | 149 |---------------| 150 | export | 151 | table | 152 |---------------| 153 | uid/gid | 154 | lookup table | 155 |---------------| 156 | xattr | 157 | table | 158 --------------- 159 160Compressed data blocks are written to the filesystem as files are read from 161the source directory, and checked for duplicates. Once all file data has been 162written the completed inode, directory, fragment, export, uid/gid lookup and 163xattr tables are written. 164 1653.1 Compression options 166----------------------- 167 168Compressors can optionally support compression specific options (e.g. 169dictionary size). If non-default compression options have been used, then 170these are stored here. 171 1723.2 Inodes 173---------- 174 175Metadata (inodes and directories) are compressed in 8Kbyte blocks. Each 176compressed block is prefixed by a two byte length, the top bit is set if the 177block is uncompressed. A block will be uncompressed if the -noI option is set, 178or if the compressed block was larger than the uncompressed block. 179 180Inodes are packed into the metadata blocks, and are not aligned to block 181boundaries, therefore inodes overlap compressed blocks. Inodes are identified 182by a 48-bit number which encodes the location of the compressed metadata block 183containing the inode, and the byte offset into that block where the inode is 184placed (<block, offset>). 185 186To maximise compression there are different inodes for each file type 187(regular file, directory, device, etc.), the inode contents and length 188varying with the type. 189 190To further maximise compression, two types of regular file inode and 191directory inode are defined: inodes optimised for frequently occurring 192regular files and directories, and extended types where extra 193information has to be stored. 194 1953.3 Directories 196--------------- 197 198Like inodes, directories are packed into compressed metadata blocks, stored 199in a directory table. Directories are accessed using the start address of 200the metablock containing the directory and the offset into the 201decompressed block (<block, offset>). 202 203Directories are organised in a slightly complex way, and are not simply 204a list of file names. The organisation takes advantage of the 205fact that (in most cases) the inodes of the files will be in the same 206compressed metadata block, and therefore, can share the start block. 207Directories are therefore organised in a two level list, a directory 208header containing the shared start block value, and a sequence of directory 209entries, each of which share the shared start block. A new directory header 210is written once/if the inode start block changes. The directory 211header/directory entry list is repeated as many times as necessary. 212 213Directories are sorted, and can contain a directory index to speed up 214file lookup. Directory indexes store one entry per metablock, each entry 215storing the index/filename mapping to the first directory header 216in each metadata block. Directories are sorted in alphabetical order, 217and at lookup the index is scanned linearly looking for the first filename 218alphabetically larger than the filename being looked up. At this point the 219location of the metadata block the filename is in has been found. 220The general idea of the index is to ensure only one metadata block needs to be 221decompressed to do a lookup irrespective of the length of the directory. 222This scheme has the advantage that it doesn't require extra memory overhead 223and doesn't require much extra storage on disk. 224 2253.4 File data 226------------- 227 228Regular files consist of a sequence of contiguous compressed blocks, and/or a 229compressed fragment block (tail-end packed block). The compressed size 230of each datablock is stored in a block list contained within the 231file inode. 232 233To speed up access to datablocks when reading 'large' files (256 Mbytes or 234larger), the code implements an index cache that caches the mapping from 235block index to datablock location on disk. 236 237The index cache allows Squashfs to handle large files (up to 1.75 TiB) while 238retaining a simple and space-efficient block list on disk. The cache 239is split into slots, caching up to eight 224 GiB files (128 KiB blocks). 240Larger files use multiple slots, with 1.75 TiB files using all 8 slots. 241The index cache is designed to be memory efficient, and by default uses 24216 KiB. 243 2443.5 Fragment lookup table 245------------------------- 246 247Regular files can contain a fragment index which is mapped to a fragment 248location on disk and compressed size using a fragment lookup table. This 249fragment lookup table is itself stored compressed into metadata blocks. 250A second index table is used to locate these. This second index table for 251speed of access (and because it is small) is read at mount time and cached 252in memory. 253 2543.6 Uid/gid lookup table 255------------------------ 256 257For space efficiency regular files store uid and gid indexes, which are 258converted to 32-bit uids/gids using an id look up table. This table is 259stored compressed into metadata blocks. A second index table is used to 260locate these. This second index table for speed of access (and because it 261is small) is read at mount time and cached in memory. 262 2633.7 Export table 264---------------- 265 266To enable Squashfs filesystems to be exportable (via NFS etc.) filesystems 267can optionally (disabled with the -no-exports Mksquashfs option) contain 268an inode number to inode disk location lookup table. This is required to 269enable Squashfs to map inode numbers passed in filehandles to the inode 270location on disk, which is necessary when the export code reinstantiates 271expired/flushed inodes. 272 273This table is stored compressed into metadata blocks. A second index table is 274used to locate these. This second index table for speed of access (and because 275it is small) is read at mount time and cached in memory. 276 2773.8 Xattr table 278--------------- 279 280The xattr table contains extended attributes for each inode. The xattrs 281for each inode are stored in a list, each list entry containing a type, 282name and value field. The type field encodes the xattr prefix 283("user.", "trusted." etc) and it also encodes how the name/value fields 284should be interpreted. Currently the type indicates whether the value 285is stored inline (in which case the value field contains the xattr value), 286or if it is stored out of line (in which case the value field stores a 287reference to where the actual value is stored). This allows large values 288to be stored out of line improving scanning and lookup performance and it 289also allows values to be de-duplicated, the value being stored once, and 290all other occurrences holding an out of line reference to that value. 291 292The xattr lists are packed into compressed 8K metadata blocks. 293To reduce overhead in inodes, rather than storing the on-disk 294location of the xattr list inside each inode, a 32-bit xattr id 295is stored. This xattr id is mapped into the location of the xattr 296list using a second xattr id lookup table. 297 2984. TODOs and Outstanding Issues 299------------------------------- 300 3014.1 TODO list 302------------- 303 304Implement ACL support. 305 3064.2 Squashfs Internal Cache 307--------------------------- 308 309Blocks in Squashfs are compressed. To avoid repeatedly decompressing 310recently accessed data Squashfs uses two small metadata and fragment caches. 311 312The cache is not used for file datablocks, these are decompressed and cached in 313the page-cache in the normal way. The cache is used to temporarily cache 314fragment and metadata blocks which have been read as a result of a metadata 315(i.e. inode or directory) or fragment access. Because metadata and fragments 316are packed together into blocks (to gain greater compression) the read of a 317particular piece of metadata or fragment will retrieve other metadata/fragments 318which have been packed with it, these because of locality-of-reference may be 319read in the near future. Temporarily caching them ensures they are available 320for near future access without requiring an additional read and decompress. 321 322In the future this internal cache may be replaced with an implementation which 323uses the kernel page cache. Because the page cache operates on page sized 324units this may introduce additional complexity in terms of locking and 325associated race conditions. 326