1 .. SPDX-License-Identifier: GPL-2.0
2
3 =======================
4 Squashfs 4.0 Filesystem
5 =======================
6
7 Squashfs is a compressed read-only filesystem for Linux.
8
9 It uses zlib, lz4, lzo, or xz compression to compress files, inodes and
10 directories. Inodes in the system are very small and all blocks are packed to
11 minimise data overhead. Block sizes greater than 4K are supported up to a
12 maximum of 1Mbytes (default block size 128K).
13
14 Squashfs is intended for general read-only filesystem use, for archival
15 use (i.e. in cases where a .tar.gz file may be used), and in constrained
16 block device/memory systems (e.g. embedded systems) where low overhead is
17 needed.
18
19 Mailing list: squashfs-devel@lists.sourceforge.net
20 Web site: www.squashfs.org
21
22 1. Filesystem Features
23 ----------------------
24
25 Squashfs filesystem features versus Cramfs:
26
27 ============================== ========= ==========
28 Squashfs Cramfs
29 ============================== ========= ==========
30 Max filesystem size 2^64 256 MiB
31 Max file size ~ 2 TiB 16 MiB
32 Max files unlimited unlimited
33 Max directories unlimited unlimited
34 Max entries per directory unlimited unlimited
35 Max block size 1 MiB 4 KiB
36 Metadata compression yes no
37 Directory indexes yes no
38 Sparse file support yes no
39 Tail-end packing (fragments) yes no
40 Exportable (NFS etc.) yes no
41 Hard link support yes no
42 "." and ".." in readdir yes no
43 Real inode numbers yes no
44 32-bit uids/gids yes no
45 File creation time yes no
46 Xattr support yes no
47 ACL support no no
48 ============================== ========= ==========
49
50 Squashfs compresses data, inodes and directories. In addition, inode and
51 directory data are highly compacted, and packed on byte boundaries. Each
52 compressed inode is on average 8 bytes in length (the exact length varies on
53 file type, i.e. regular file, directory, symbolic link, and block/char device
54 inodes have different sizes).
55
56 2. Using Squashfs
57 -----------------
58
59 As squashfs is a read-only filesystem, the mksquashfs program must be used to
60 create populated squashfs filesystems. This and other squashfs utilities
61 can be obtained from http://www.squashfs.org. Usage instructions can be
62 obtained from this site also.
63
64 The squashfs-tools development tree is now located on kernel.org
65 git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git
66
67 2.1 Mount options
68 -----------------
69 =================== =========================================================
70 errors=%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 ========== =============================================
83 threads=%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
127 3. Squashfs Filesystem Design
128 -----------------------------
129
130 A squashfs filesystem consists of a maximum of nine parts, packed together on a
131 byte 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
160 Compressed data blocks are written to the filesystem as files are read from
161 the source directory, and checked for duplicates. Once all file data has been
162 written the completed inode, directory, fragment, export, uid/gid lookup and
163 xattr tables are written.
164
165 3.1 Compression options
166 -----------------------
167
168 Compressors can optionally support compression specific options (e.g.
169 dictionary size). If non-default compression options have been used, then
170 these are stored here.
171
172 3.2 Inodes
173 ----------
174
175 Metadata (inodes and directories) are compressed in 8Kbyte blocks. Each
176 compressed block is prefixed by a two byte length, the top bit is set if the
177 block is uncompressed. A block will be uncompressed if the -noI option is set,
178 or if the compressed block was larger than the uncompressed block.
179
180 Inodes are packed into the metadata blocks, and are not aligned to block
181 boundaries, therefore inodes overlap compressed blocks. Inodes are identified
182 by a 48-bit number which encodes the location of the compressed metadata block
183 containing the inode, and the byte offset into that block where the inode is
184 placed (<block, offset>).
185
186 To maximise compression there are different inodes for each file type
187 (regular file, directory, device, etc.), the inode contents and length
188 varying with the type.
189
190 To further maximise compression, two types of regular file inode and
191 directory inode are defined: inodes optimised for frequently occurring
192 regular files and directories, and extended types where extra
193 information has to be stored.
194
195 3.3 Directories
196 ---------------
197
198 Like inodes, directories are packed into compressed metadata blocks, stored
199 in a directory table. Directories are accessed using the start address of
200 the metablock containing the directory and the offset into the
201 decompressed block (<block, offset>).
202
203 Directories are organised in a slightly complex way, and are not simply
204 a list of file names. The organisation takes advantage of the
205 fact that (in most cases) the inodes of the files will be in the same
206 compressed metadata block, and therefore, can share the start block.
207 Directories are therefore organised in a two level list, a directory
208 header containing the shared start block value, and a sequence of directory
209 entries, each of which share the shared start block. A new directory header
210 is written once/if the inode start block changes. The directory
211 header/directory entry list is repeated as many times as necessary.
212
213 Directories are sorted, and can contain a directory index to speed up
214 file lookup. Directory indexes store one entry per metablock, each entry
215 storing the index/filename mapping to the first directory header
216 in each metadata block. Directories are sorted in alphabetical order,
217 and at lookup the index is scanned linearly looking for the first filename
218 alphabetically larger than the filename being looked up. At this point the
219 location of the metadata block the filename is in has been found.
220 The general idea of the index is to ensure only one metadata block needs to be
221 decompressed to do a lookup irrespective of the length of the directory.
222 This scheme has the advantage that it doesn't require extra memory overhead
223 and doesn't require much extra storage on disk.
224
225 3.4 File data
226 -------------
227
228 Regular files consist of a sequence of contiguous compressed blocks, and/or a
229 compressed fragment block (tail-end packed block). The compressed size
230 of each datablock is stored in a block list contained within the
231 file inode.
232
233 To speed up access to datablocks when reading 'large' files (256 Mbytes or
234 larger), the code implements an index cache that caches the mapping from
235 block index to datablock location on disk.
236
237 The index cache allows Squashfs to handle large files (up to 1.75 TiB) while
238 retaining a simple and space-efficient block list on disk. The cache
239 is split into slots, caching up to eight 224 GiB files (128 KiB blocks).
240 Larger files use multiple slots, with 1.75 TiB files using all 8 slots.
241 The index cache is designed to be memory efficient, and by default uses
242 16 KiB.
243
244 3.5 Fragment lookup table
245 -------------------------
246
247 Regular files can contain a fragment index which is mapped to a fragment
248 location on disk and compressed size using a fragment lookup table. This
249 fragment lookup table is itself stored compressed into metadata blocks.
250 A second index table is used to locate these. This second index table for
251 speed of access (and because it is small) is read at mount time and cached
252 in memory.
253
254 3.6 Uid/gid lookup table
255 ------------------------
256
257 For space efficiency regular files store uid and gid indexes, which are
258 converted to 32-bit uids/gids using an id look up table. This table is
259 stored compressed into metadata blocks. A second index table is used to
260 locate these. This second index table for speed of access (and because it
261 is small) is read at mount time and cached in memory.
262
263 3.7 Export table
264 ----------------
265
266 To enable Squashfs filesystems to be exportable (via NFS etc.) filesystems
267 can optionally (disabled with the -no-exports Mksquashfs option) contain
268 an inode number to inode disk location lookup table. This is required to
269 enable Squashfs to map inode numbers passed in filehandles to the inode
270 location on disk, which is necessary when the export code reinstantiates
271 expired/flushed inodes.
272
273 This table is stored compressed into metadata blocks. A second index table is
274 used to locate these. This second index table for speed of access (and because
275 it is small) is read at mount time and cached in memory.
276
277 3.8 Xattr table
278 ---------------
279
280 The xattr table contains extended attributes for each inode. The xattrs
281 for each inode are stored in a list, each list entry containing a type,
282 name and value field. The type field encodes the xattr prefix
283 ("user.", "trusted." etc) and it also encodes how the name/value fields
284 should be interpreted. Currently the type indicates whether the value
285 is stored inline (in which case the value field contains the xattr value),
286 or if it is stored out of line (in which case the value field stores a
287 reference to where the actual value is stored). This allows large values
288 to be stored out of line improving scanning and lookup performance and it
289 also allows values to be de-duplicated, the value being stored once, and
290 all other occurrences holding an out of line reference to that value.
291
292 The xattr lists are packed into compressed 8K metadata blocks.
293 To reduce overhead in inodes, rather than storing the on-disk
294 location of the xattr list inside each inode, a 32-bit xattr id
295 is stored. This xattr id is mapped into the location of the xattr
296 list using a second xattr id lookup table.
297
298 4. TODOs and Outstanding Issues
299 -------------------------------
300
301 4.1 TODO list
302 -------------
303
304 Implement ACL support.
305
306 4.2 Squashfs Internal Cache
307 ---------------------------
308
309 Blocks in Squashfs are compressed. To avoid repeatedly decompressing
310 recently accessed data Squashfs uses two small metadata and fragment caches.
311
312 The cache is not used for file datablocks, these are decompressed and cached in
313 the page-cache in the normal way. The cache is used to temporarily cache
314 fragment 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
316 are packed together into blocks (to gain greater compression) the read of a
317 particular piece of metadata or fragment will retrieve other metadata/fragments
318 which have been packed with it, these because of locality-of-reference may be
319 read in the near future. Temporarily caching them ensures they are available
320 for near future access without requiring an additional read and decompress.
321
322 In the future this internal cache may be replaced with an implementation which
323 uses the kernel page cache. Because the page cache operates on page sized
324 units this may introduce additional complexity in terms of locking and
325 associated race conditions.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.