.SQUASHFS File Format

Introduction

SquashFS 3 is the version of the compressed read-only Linux filesystem that came before version 4: 3.0 appeared in 2006 and 3.1 added an inode lookup table so that a filesystem can be exported over NFS. It was the filesystem of most router and set-top-box firmware of its time, so it is found inside firmware images, often with a vendor’s changes. It compresses with gzip only. Version 3 is not the format of today’s kernels, but unsquashfs still reads it.

The file starts with hsqs (little-endian) or sqsh (big-endian), the same magic as version 4; the major version number 3 at byte 28 tells the two apart. Vendors who compressed with LZMA instead of gzip changed the magic to shsq (little-endian) or qshs (big-endian).

How it works

The structure is that of version 4, built from different parts. A 119-byte superblock gives the block size and the file offset of each table. Files are cut into blocks, each compressed on its own, with the short tail of a file in a fragment block shared with other tails, and blocks that are all zeros stored as nothing at all (a size of 0). The inodes and the directory listings are in metadata blocks of at most 8 KiB, and the inodes pack their small fields into bit-fields. The user and group ids are not in metadata blocks but in two plain arrays at the end of the file. There are no extended attributes.

In the explorer

Drop a .squashfs, .sqsh or .sfs file. The explorer reads the version from the file and shows version 3 as it does version 4: a structure tree that covers every byte (the superblock with a node for every field, the data region by file and block, the inode and directory tables as metadata blocks, the fragment and lookup tables with their indexes, the uid and gid arrays, the padding) and the tables Files, Directory entries, Inodes, Directory indexes, Fragments, Lookup table, Ids, Metadata blocks, Data blocks and Problems. Files open decompressed on demand and in windows when large, and a damaged image is reported, never hung on. Both byte orders are read; the explorer checks the bit-fields of the big-endian form as the tools lay them out.

Not described

The layouts are those of the squashfs-tools 3.4 source (squashfs_fs.h and its swap macros, which give the position of every bit-field). No program that writes version 3 runs on the machine that built these pages: the test images were written by a script from those definitions, and unsquashfs 4.7.5, which reads version 3 in both byte orders, agrees with the explorer on every listed path, field and file byte of them.

Known, not yet covered

• Viewer: the LZMA variants of vendors’ builds (the shsq and qshs magics) are recognised and their blocks decoded as LZMA with a 13-byte header, but no real image was available to check that the vendor’s stream is the same; other vendor changes (a different inode layout, a changed header) are not covered.
• Viewer: every metadata block of the test images is stored uncompressed; compressed metadata blocks use the code the version 4 tests check.

Unknown

• Reference and Viewer: no real firmware image in version 3 was available, so the form found in the wild (vendor patches included) is unchecked.

Variants

• SquashFS 4.0 filesystem – the current format: six compressors, extended attributes, little- or big-endian
• SquashFS 3 filesystem – gzip only, bit-field inodes, fragments, sparse blocks, a lookup table for NFS (3.1)
• SquashFS 2 filesystem – fragments, no inode numbers or link counts
• SquashFS 1 filesystem – the first version: no fragments, 16-bit block sizes

Links