1SQUASHFS 4.0 FILESYSTEM 2======================= 3 4Squashfs is a compressed read-only filesystem for Linux. 5It uses zlib, lz4, lzo, or xz compression to compress files, inodes and 6directories. Inodes in the system are very small and all blocks are packed to 7minimise data overhead. Block sizes greater than 4K are supported up to a 8maximum of 1Mbytes (default block size 128K). 9 10Squashfs is intended for general read-only filesystem use, for archival 11use (i.e. in cases where a .tar.gz file may be used), and in constrained 12block device/memory systems (e.g. embedded systems) where low overhead is 13needed. 14 15Mailing list: squashfs-devel@lists.sourceforge.net 16Web site: www.squashfs.org 17 181. FILESYSTEM FEATURES 19---------------------- 20 21Squashfs filesystem features versus Cramfs: 22 23 Squashfs Cramfs 24 25Max filesystem size: 2^64 256 MiB 26Max file size: ~ 2 TiB 16 MiB 27Max files: unlimited unlimited 28Max directories: unlimited unlimited 29Max entries per directory: unlimited unlimited 30Max block size: 1 MiB 4 KiB 31Metadata compression: yes no 32Directory indexes: yes no 33Sparse file support: yes no 34Tail-end packing (fragments): yes no 35Exportable (NFS etc.): yes no 36Hard link support: yes no 37"." and ".." in readdir: yes no 38Real inode numbers: yes no 3932-bit uids/gids: yes no 40File creation time: yes no 41Xattr support: yes no 42ACL support: no no 43 44Squashfs compresses data, inodes and directories. In addition, inode and 45directory data are highly compacted, and packed on byte boundaries. Each 46compressed inode is on average 8 bytes in length (the exact length varies on 47file type, i.e. regular file, directory, symbolic link, and block/char device 48inodes have different sizes). 49 502. USING SQUASHFS 51----------------- 52 53As squashfs is a read-only filesystem, the mksquashfs program must be used to 54create populated squashfs filesystems. This and other squashfs utilities 55can be obtained from http://www.squashfs.org. Usage instructions can be 56obtained from this site also. 57 58The squashfs-tools development tree is now located on kernel.org 59 git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git 60 613. SQUASHFS FILESYSTEM DESIGN 62----------------------------- 63 64A squashfs filesystem consists of a maximum of nine parts, packed together on a 65byte alignment: 66 67 --------------- 68 | superblock | 69 |---------------| 70 | compression | 71 | options | 72 |---------------| 73 | datablocks | 74 | & fragments | 75 |---------------| 76 | inode table | 77 |---------------| 78 | directory | 79 | table | 80 |---------------| 81 | fragment | 82 | table | 83 |---------------| 84 | export | 85 | table | 86 |---------------| 87 | uid/gid | 88 | lookup table | 89 |---------------| 90 | xattr | 91 | table | 92 --------------- 93 94Compressed data blocks are written to the filesystem as files are read from 95the source directory, and checked for duplicates. Once all file data has been 96written the completed inode, directory, fragment, export, uid/gid lookup and 97xattr tables are written. 98 993.1 Compression options 100----------------------- 101 102Compressors can optionally support compression specific options (e.g. 103dictionary size). If non-default compression options have been used, then 104these are stored here. 105 1063.2 Inodes 107---------- 108 109Metadata (inodes and directories) are compressed in 8Kbyte blocks. Each 110compressed block is prefixed by a two byte length, the top bit is set if the 111block is uncompressed. A block will be uncompressed if the -noI option is set, 112or if the compressed block was larger than the uncompressed block. 113 114Inodes are packed into the metadata blocks, and are not aligned to block 115boundaries, therefore inodes overlap compressed blocks. Inodes are identified 116by a 48-bit number which encodes the location of the compressed metadata block 117containing the inode, and the byte offset into that block where the inode is 118placed (<block, offset>). 119 120To maximise compression there are different inodes for each file type 121(regular file, directory, device, etc.), the inode contents and length 122varying with the type. 123 124To further maximise compression, two types of regular file inode and 125directory inode are defined: inodes optimised for frequently occurring 126regular files and directories, and extended types where extra 127information has to be stored. 128 1293.3 Directories 130--------------- 131 132Like inodes, directories are packed into compressed metadata blocks, stored 133in a directory table. Directories are accessed using the start address of 134the metablock containing the directory and the offset into the 135decompressed block (<block, offset>). 136 137Directories are organised in a slightly complex way, and are not simply 138a list of file names. The organisation takes advantage of the 139fact that (in most cases) the inodes of the files will be in the same 140compressed metadata block, and therefore, can share the start block. 141Directories are therefore organised in a two level list, a directory 142header containing the shared start block value, and a sequence of directory 143entries, each of which share the shared start block. A new directory header 144is written once/if the inode start block changes. The directory 145header/directory entry list is repeated as many times as necessary. 146 147Directories are sorted, and can contain a directory index to speed up 148file lookup. Directory indexes store one entry per metablock, each entry 149storing the index/filename mapping to the first directory header 150in each metadata block. Directories are sorted in alphabetical order, 151and at lookup the index is scanned linearly looking for the first filename 152alphabetically larger than the filename being looked up. At this point the 153location of the metadata block the filename is in has been found. 154The general idea of the index is to ensure only one metadata block needs to be 155decompressed to do a lookup irrespective of the length of the directory. 156This scheme has the advantage that it doesn't require extra memory overhead 157and doesn't require much extra storage on disk. 158 1593.4 File data 160------------- 161 162Regular files consist of a sequence of contiguous compressed blocks, and/or a 163compressed fragment block (tail-end packed block). The compressed size 164of each datablock is stored in a block list contained within the 165file inode. 166 167To speed up access to datablocks when reading 'large' files (256 Mbytes or 168larger), the code implements an index cache that caches the mapping from 169block index to datablock location on disk. 170 171The index cache allows Squashfs to handle large files (up to 1.75 TiB) while 172retaining a simple and space-efficient block list on disk. The cache 173is split into slots, caching up to eight 224 GiB files (128 KiB blocks). 174Larger files use multiple slots, with 1.75 TiB files using all 8 slots. 175The index cache is designed to be memory efficient, and by default uses 17616 KiB. 177 1783.5 Fragment lookup table 179------------------------- 180 181Regular files can contain a fragment index which is mapped to a fragment 182location on disk and compressed size using a fragment lookup table. This 183fragment lookup table is itself stored compressed into metadata blocks. 184A second index table is used to locate these. This second index table for 185speed of access (and because it is small) is read at mount time and cached 186in memory. 187 1883.6 Uid/gid lookup table 189------------------------ 190 191For space efficiency regular files store uid and gid indexes, which are 192converted to 32-bit uids/gids using an id look up table. This table is 193stored compressed into metadata blocks. A second index table is used to 194locate these. This second index table for speed of access (and because it 195is small) is read at mount time and cached in memory. 196 1973.7 Export table 198---------------- 199 200To enable Squashfs filesystems to be exportable (via NFS etc.) filesystems 201can optionally (disabled with the -no-exports Mksquashfs option) contain 202an inode number to inode disk location lookup table. This is required to 203enable Squashfs to map inode numbers passed in filehandles to the inode 204location on disk, which is necessary when the export code reinstantiates 205expired/flushed inodes. 206 207This table is stored compressed into metadata blocks. A second index table is 208used to locate these. This second index table for speed of access (and because 209it is small) is read at mount time and cached in memory. 210 2113.8 Xattr table 212--------------- 213 214The xattr table contains extended attributes for each inode. The xattrs 215for each inode are stored in a list, each list entry containing a type, 216name and value field. The type field encodes the xattr prefix 217("user.", "trusted." etc) and it also encodes how the name/value fields 218should be interpreted. Currently the type indicates whether the value 219is stored inline (in which case the value field contains the xattr value), 220or if it is stored out of line (in which case the value field stores a 221reference to where the actual value is stored). This allows large values 222to be stored out of line improving scanning and lookup performance and it 223also allows values to be de-duplicated, the value being stored once, and 224all other occurrences holding an out of line reference to that value. 225 226The xattr lists are packed into compressed 8K metadata blocks. 227To reduce overhead in inodes, rather than storing the on-disk 228location of the xattr list inside each inode, a 32-bit xattr id 229is stored. This xattr id is mapped into the location of the xattr 230list using a second xattr id lookup table. 231 2324. TODOS AND OUTSTANDING ISSUES 233------------------------------- 234 2354.1 Todo list 236------------- 237 238Implement ACL support. 239 2404.2 Squashfs internal cache 241--------------------------- 242 243Blocks in Squashfs are compressed. To avoid repeatedly decompressing 244recently accessed data Squashfs uses two small metadata and fragment caches. 245 246The cache is not used for file datablocks, these are decompressed and cached in 247the page-cache in the normal way. The cache is used to temporarily cache 248fragment and metadata blocks which have been read as a result of a metadata 249(i.e. inode or directory) or fragment access. Because metadata and fragments 250are packed together into blocks (to gain greater compression) the read of a 251particular piece of metadata or fragment will retrieve other metadata/fragments 252which have been packed with it, these because of locality-of-reference may be 253read in the near future. Temporarily caching them ensures they are available 254for near future access without requiring an additional read and decompress. 255 256In the future this internal cache may be replaced with an implementation which 257uses the kernel page cache. Because the page cache operates on page sized 258units this may introduce additional complexity in terms of locking and 259associated race conditions. 260