Documentation/filesystems/squashfs.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 Squashfs is a compressed read-only filesystem for Linux.
11 minimise data overhead. Block sizes greater than 4K are supported up to a
12 maximum of 1Mbytes (default block size 128K).
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
19 Mailing list: squashfs-devel@lists.sourceforge.net
23 ----------------------
30 Max filesystem size		2^64			256 MiB
31 Max file size			~ 2 TiB			16 MiB
35 Max block size			1 MiB			4 KiB
39 Tail-end packing (fragments)	yes			no
44 32-bit uids/gids		yes			no
53 file type, i.e. regular file, directory, symbolic link, and block/char device
57 -----------------
59 As squashfs is a read-only filesystem, the mksquashfs program must be used to
64 The squashfs-tools development tree is now located on kernel.org
65 	git://git.kernel.org/pub/scm/fs/squashfs/squashfs-tools.git
68 -----------------
88                            single  use single-threaded decompression (default)
90                                    Only one block (data or metadata) can be
93                                    also gives poor performance on parallel I/O
98                                    If you have a parallel I/O workload and your
100                                    may improve overall I/O performance. It
106                                    decompression is load-balanced across the
128 -----------------------------
133 	 ---------------
135 	|---------------|
138 	|---------------|
141 	|---------------|
143 	|---------------|
146 	|---------------|
149 	|---------------|
152 	|---------------|
155 	|---------------|
158 	 ---------------
166 -----------------------
169 dictionary size).  If non-default compression options have been used, then
173 ----------
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.
180 Inodes are packed into the metadata blocks, and are not aligned to block
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>).
196 ---------------
201 decompressed block (<block, offset>).
206 compressed metadata block, and therefore, can share the start block.
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
216 in each metadata block.  Directories are sorted in alphabetical order,
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
226 -------------
229 compressed fragment block (tail-end packed block).   The compressed size
230 of each datablock is stored in a block list contained within the
234 larger), the code implements an index cache that caches the mapping from
235 block index to datablock location on disk.
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
241 The index cache is designed to be memory efficient, and by default uses
245 -------------------------
248 location on disk and compressed size using a fragment lookup table.  This
255 ------------------------
258 converted to 32-bit uids/gids using an id look up table.  This table is
264 ----------------
267 can optionally (disabled with the -no-exports Mksquashfs option) contain
278 ---------------
289 also allows values to be de-duplicated, the value being stored once, and
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
299 -------------------------------
302 -------------
306 4.2 Squashfs Internal Cache
307 ---------------------------
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
315 (i.e. inode or directory) or fragment access.  Because metadata and fragments
318 which have been packed with it, these because of locality-of-reference may be
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