squashfs

This is a read-only implementation of squashfs initially meant to be use with go-fuse.

Since then, golang added io/fs and fuse support was moved to a fuse tag, which means this module can be either used with go-fuse, or as a simple io/fs-compliant squashfs file reader.

Tags

The following tags can be specified on build to enable/disable features:

• fuse adds methods to the Inode object to interact with fuse
• xz adds a dependency on github.com/ulikunitz/xz to support XZ compressed files
• zstd adds a dependency on github.com/klauspost/compress/zstd to support ZSTD compressed files

By default, only GZip compression is supported as to limit dependency on external libraries. The following can be easily enabled by adding a single line before any call to the library:

zstd

import "github.com/klauspost/compress/zstd"

func init() {
    squashfs.RegisterCompHandler(squashfs.ZSTD, &squashfs.CompHandler{
        Decompress: squashfs.MakeDecompressor(zstd.ZipDecompressor()),
    })
}

xz

import (
    "io"

    "github.com/ulikunitz/xz"
)

func init() {
    squashfs.RegisterCompHandler(squashfs.XZ, &squashfs.CompHandler{
        Decompress: squashfs.MakeDecompressorErr(func(r io.Reader) (io.ReadCloser, error) {
            rc, err := xz.NewReader(r)
            if err != nil {
                return nil, err
            }
            return io.NopCloser(rc), nil
        }),
    })
}

Others

LZMA, LZO and LZ4 are also defined by squashfs and can be enabled similarly.

Example usage

Basic file access

sqfs, err := squashfs.Open("file.squashfs")
if err != nil {
    return err
}
defer sqfs.Close()

// sqfs can be used as a regular fs.FS
data, err := fs.ReadFile(sqfs, "dir/file.txt")
if err != nil {
    return err
}

// Or serve files over HTTP
http.Handle("/", http.FileServer(sqfs))

Reading directories

// List directory contents
entries, err := sqfs.ReadDir("some/directory")
if err != nil {
    return err
}

// Process directory entries
for _, entry := range entries {
    fmt.Printf("Name: %s, IsDir: %v\n", entry.Name(), entry.IsDir())
    
    // Get more info if needed
    info, err := entry.Info()
    if err != nil {
        return err
    }
    fmt.Printf("Size: %d, Mode: %s\n", info.Size(), info.Mode())
}

Reading symlinks

// Read a symlink target
target, err := sqfs.Readlink("path/to/symlink")
if err != nil {
    return err
}
fmt.Printf("Symlink points to: %s\n", target)

Custom compression support

// Register XZ support (requires "xz" build tag)
import (
    "github.com/KarpelesLab/squashfs"
    "github.com/ulikunitz/xz"
)

// Register XZ decompressor at init time
func init() {
    squashfs.RegisterCompHandler(squashfs.XZ, &squashfs.CompHandler{
        Decompress: squashfs.MakeDecompressorErr(xz.NewReader),
    })
}

For more examples, see the test files in the project.

File format

Some documentation is available online on SquashFS.

• https://dr-emann.github.io/squashfs/
• https://dr-emann.github.io/squashfs/squashfs.html

Features

• Read-only implementation of squashfs compatible with Go's io/fs interface
• Optional FUSE support with the fuse build tag
• Support for GZip compression by default, with XZ and ZSTD available via build tags
• Extensible compression support through the RegisterCompHandler API
• Directory index support for fast access to files in large directories
• Symlink support
• CLI tool for exploring and extracting files from SquashFS archives

CLI Tool

A command-line interface tool is provided in the cmd/sqfs directory. This tool allows you to:

• List files in a SquashFS archive
• View the contents of files inside a SquashFS archive
• Display detailed information about SquashFS archives

Usage

sqfs - SquashFS CLI tool

Usage:
  sqfs ls <squashfs_file> [<path>]          List files in SquashFS (optionally in a specific path)
  sqfs cat <squashfs_file> <file>           Display contents of a file in SquashFS
  sqfs info <squashfs_file>                 Display information about a SquashFS archive
  sqfs help                                 Show this help message

Examples:
  sqfs ls archive.squashfs                  List all files at the root of archive.squashfs
  sqfs ls archive.squashfs lib              List all files in the lib directory
  sqfs cat archive.squashfs dir/file.txt    Display contents of file.txt from archive.squashfs
  sqfs info archive.squashfs                Show metadata about the SquashFS archive

Installing the CLI Tool

go install github.com/KarpelesLab/squashfs/cmd/sqfs@latest

To install with additional compression support:

go install -tags "xz zstd" github.com/KarpelesLab/squashfs/cmd/sqfs@latest

Performance

As of November 2024, directory indexes are now used for efficient file lookup in large directories, significantly improving performance for random file access.