Build a Reproducible Squashfs Image from a Tar Archive

A squashfs image built straight from a tar file inherits whatever ownership and timestamps came with it, and sqfstar will not warn you. This guide builds a compressed, read-only Squashfs image from a tar archive with sqfstar, then runs the checks that prove which files and metadata actually went into it. The examples use sqfstar from Squashfs-tools 4.6.1, installed here as package version 1:4.6.1-1build1.

Allow about fifteen minutes. You need sqfstar, a tar archive, enough free space for the output image, and unsquashfs for verification. The build normally needs no elevated privileges. Use sudo only when your input or destination is deliberately restricted, and check the resulting ownership and permissions before treating the image as a system artefact.

1. Check the installed tool

Confirm the binary and version before relying on option details. This is read-only:

$ command -v sqfstar
/usr/bin/sqfstar
$ dpkg-query -W -f='${Package} ${Version}\n' squashfs-tools
squashfs-tools 1:4.6.1-1build1
$ sqfstar -version | sed -n '1,2p'
sqfstar version 4.6.1 (2023/03/25)

If your package is a different release, read its local manual before copying the option combinations below. The examples here match the installed 4.6.1 interface.

2. Build a basic image from tar

sqfstar reads the tar stream on standard input. Its positional output path comes before optional exclude names:

$ sqfstar /path/to/rootfs.sqfs < /path/to/rootfs.tar

You can feed it compressed tar data through a decompressor, so an intermediate uncompressed file is not required:

$ zcat /path/to/rootfs.tar.gz | sqfstar /path/to/rootfs.sqfs
$ xzcat /path/to/rootfs.tar.xz | sqfstar /path/to/rootfs.sqfs
$ zstdcat /path/to/rootfs.tar.zst | sqfstar /path/to/rootfs.sqfs

The default block size is 128 Kbytes and the default compressor is normally gzip. The command writes a binary image, not a directory tree. Do not redirect its output to the image: standard input is the tar stream, while the image name is an argument.

Checkpoint: a successful build should leave the named file and return status zero:

$ test -s /path/to/rootfs.sqfs && echo 'image exists and is non-empty'
image exists and is non-empty

3. Choose compression and reproducibility settings

For a deliberate compression choice, select one of the compressors reported by the manual. This example uses Zstandard and a 1 MiB data block:

$ sqfstar -comp zstd -b 1M /path/to/rootfs-zstd.sqfs < /path/to/rootfs.tar

Large blocks can improve compression for some data but can increase memory or access costs. Keep the default until you have measured a reason to change it. -b accepts a number with an optional K or M suffix, and the documented maximum is 1 Mbyte.

Reproducible output is the default in this release. For stable metadata, set ownership and timestamps explicitly when the archive's values are not part of your intended result:

$ sqfstar -comp zstd \
    -root-uid 0 -root-gid 0 -root-mode 0755 \
    -mkfs-time 0 -all-time 0 \
    /path/to/rootfs-reproducible.sqfs < /path/to/rootfs.tar

The SOURCE_DATE_EPOCH environment variable also supplies the filesystem creation timestamp, and timestamps later than it are clamped. If you use it in a build, record the value in the build configuration rather than relying on a shell session that somebody may forget to reproduce.

Checkpoint: run the same command twice with the same input and settings, then compare hashes:

$ sha256sum /path/to/rootfs-reproducible-a.sqfs /path/to/rootfs-reproducible-b.sqfs
same-hash  /path/to/rootfs-reproducible-a.sqfs
same-hash  /path/to/rootfs-reproducible-b.sqfs

The displayed hash will be different on your machine. The two hash values should match. If they do not, compare the input tar, timestamps, ownership and environment before calling the images reproducible.

4. Set the root directory metadata consciously

Tar archives do not necessarily describe the root directory as a separate entry. In the installed tool, the default root mode is 0777, and the default root owner and group are the user and group running sqfstar. That can be surprising in an image intended for a system or container.

Set the root metadata explicitly, and decide whether file ownership should also be normalised:

$ sqfstar \
    -root-mode 0755 -root-uid 0 -root-gid 0 \
    -all-root \
    /path/to/rootfs-root-owned.sqfs < /path/to/rootfs.tar

-all-root makes all files root-owned. Use it only when that is the intended image contract. The more targeted -force-uid and -force-gid options replace all file ids with chosen values. These settings change metadata inside the image; they do not change ownership of the tar file or the output file on the host.

5. Exclude files without shell expansion

Pass exclude patterns after the output path. Quote wildcard patterns so the shell does not expand them before sqfstar sees them:

$ sqfstar /path/to/rootfs-no-logs.sqfs '*.log' '*.tmp' < /path/to/rootfs.tar

A pattern such as *.log matches a matching file in the top-level directory. Prefix a pattern with three dots to make the wildcard non-anchored and match it anywhere in the archive:

$ sqfstar /path/to/rootfs-no-logs.sqfs '... *.log' < /path/to/rootfs.tar

For a longer or reviewed exclusion list, put one path or pattern per line in a file and use -ef:

$ sqfstar -ef /path/to/excludes.txt /path/to/rootfs-filtered.sqfs < /path/to/rootfs.tar

Exclusion is part of the image build, not a cleanup step. Keep the original tar until verification confirms that the excluded material was the only material you meant to omit.

6. Verify the image contents and metadata

Inspect the superblock before mounting anything. This is read-only and does not require root:

$ unsquashfs -s /path/to/rootfs.sqfs
Found a valid SQUASHFS 4:0 superblock on /path/to/rootfs.sqfs.
Compression gzip
Block size 131072
Filesystem is not exportable via NFS

Your output will include the actual size, timestamp, compressor and feature flags. Check those values against the build settings. In particular, confirm that the block size and compressor are the ones you selected.

List paths without extracting the image:

$ unsquashfs -ll /path/to/rootfs.sqfs
drwxr-xr-x root/root ... squashfs-root
... squashfs-root/etc/hostname

The listing is host-specific, so the timestamps, sizes and exact paths will differ. Check that required files exist, excluded files do not, and root ownership or permissions match your decision. If you need an extracted test tree, extract into a new, empty directory you have checked first. Do not extract over a live system directory.

7. Avoid overwriting a useful image

Sqfstar normally refuses to overwrite an existing output unless you pass -force. Treat -force as destructive: it can replace a valid image with a failed or incomplete build. Do not use it in a command copied into an unattended job unless replacement is explicitly part of that job's design.

A safer pattern is to build under a new name, verify it, then replace the old image as one deliberate operation:

$ sqfstar /path/to/rootfs.sqfs.new < /path/to/rootfs.tar
$ unsquashfs -s /path/to/rootfs.sqfs.new
$ unsquashfs -ll /path/to/rootfs.sqfs.new
$ mv /path/to/rootfs.sqfs.new /path/to/rootfs.sqfs

The final mv changes the destination and may disrupt a consumer that expects the old image. Check how the image is used before replacing it. If verification fails, leave the old image in place and remove the .new file after inspecting the error. If the final move has already happened, restore the previous image from your normal backup or artefact store; there is no generic undo inside sqfstar.

Done means