squashfs

squashfs

Pure-Go, read-only access to SquashFS 4.0 filesystem images — no root, no external tools, no CGO.

SquashFS is a compressed, read-only archive format used widely for live media, container/app images (snap, AppImage) and embedded/initramfs roots. This driver parses an image produced by mksquashfs and exposes it through the shared github.com/go-filesystems/interface Filesystem API.

Support summary

References

• https://dr-emann.github.io/squashfs/ (SquashFS Binary Format)
• Linux fs/squashfs/ and squashfs-tools (mksquashfs / unsquashfs)

Module

github.com/go-filesystems/squashfs

Usage

fs, err := squashfs.OpenFile("image.squashfs")
if err != nil { /* ... */ }
defer fs.Close()

data, err := fs.ReadFile("/etc/hostname")
entries, err := fs.ListDir("/")

// Create an image from a directory tree (gzip by default).
err = squashfs.BuildFromDir("out.squashfs", "/path/to/tree", squashfs.BuildOptions{})

Reading part of a file

ReadFile returns the whole file, which is no use to anything serving reads on demand — a mount, an NFS or 9P export — where a 4 KiB request out of a multi-gigabyte image must not decompress the lot. The driver implements the optional filesystem.Opener capability:

var generic filesystem.Filesystem = fs
if o, ok := generic.(filesystem.Opener); ok {
    f, err := o.OpenFile("/usr/lib/big.so")
    if err != nil { /* ... */ }
    defer f.Close()

    buf := make([]byte, 4096)
    n, err := f.ReadAt(buf, 1<<30) // only the blocks that range touches
    _, _ = n, err
    _ = f.Size()                   // from the inode; decompresses nothing
}

Compression does not rule random access out. A SquashFS file is cut into fixed-size logical blocks (block_size, 128 KiB by default) compressed independently, and the inode carries each one's on-disk length. So the block holding byte N is N/block_size, and its position on disk is the running sum of the preceding lengths — a prefix sum computed once at OpenFile over metadata already decoded. Serving a range costs the one or two blocks it touches. Decompression goes through the same block cache ReadFile uses, which matters because a fragment block is shared between many files' tails.

ReadAt follows io.ReaderAt exactly (n < len(p) only with a non-nil error, io.EOF at the end) and is safe to call concurrently.

Note the method (*FS).OpenFile(path) (filesystem.File, error) is distinct from the package-level squashfs.OpenFile(path) (*FS, error), which opens an image from the host filesystem.

Untrusted images

An image is attacker-controlled input, and in SquashFS almost every size is a claim: a 4-byte sparse block entry stands for a whole block of zeros, metadata is compressed, and a fragment of a header can name gigabytes. Every input-driven allocation is therefore bounded before it is made (bombs_test.go measures each road with runtime.MemStats):

Fuzz targets: FuzzOpenRead, FuzzReadFile, FuzzReadMetaBlock, FuzzReadDir, FuzzDecompress, FuzzReadInode, FuzzReadXattr.

Limitations

• Reading: gzip, xz, zstd, LZO, lz4 and legacy standalone lzma blocks are all decoded; xz blocks may carry the Delta and BCJ filters.
• Writing (BuildFromDir): produces gzip or uncompressed images; files are stored as full data blocks (no tail-end fragment packing yet), all owned by uid/gid 0, no xattrs. Once written, an image is immutable (no in-place edits).
• Extended attributes (xattr table) are not surfaced.
• Intended for tooling and testing.