SquashFS Setup Guide for Gershwin Workspace (Debian/Linux)

Overview

Gershwin Workspace mounts SquashFS images through /Volumes using FUSE (Filesystem in Userspace). This requires the FUSE kernel module, the squashfuse utility, and supporting libraries. The workspace also uses libsquashfs at build time for reading AppImage icons.

Required Packages

Install all required packages:

sudo apt install squashfuse fuse3 libfuse3-4 libsquashfs-dev squashfs-tools

Package	Purpose
`fuse3`	Provides `fusermount3`, the userspace mount/unmount utility that `squashfuse` calls to register mounts with the kernel. Without this, no FUSE mounts will work.
`libfuse3-4`	FUSE 3.x shared library (usually installed as a dependency of `fuse3`).
`squashfuse`	FUSE filesystem driver that mounts SquashFS archives. This is the tool invoked by `VolumeManager` when you open a `.squashfs`, `.sqsh`, or `.sfs` file.
`libsquashfs-dev`	Development headers and library for `libsquashfs` (squashfs-tools-ng). Required at build time so that `configure` detects SquashFS support (`HAVE_SQUASHFS=1`) and enables AppImage icon extraction in `AppImageIconProvider`.
`squashfs-tools`	Provides `mksquashfs` and `unsquashfs` for creating and inspecting SquashFS images.

Kernel Module

The fuse kernel module must be loaded:

# Check if loaded
lsmod | grep fuse

# Load if missing
sudo modprobe fuse

On Debian with recent kernels, FUSE is typically built-in rather than a loadable module. Verify with:

modinfo fuse

If it reports filename: (builtin), no action is needed.

FUSE Device Node

/dev/fuse must exist and be accessible:

ls -l /dev/fuse

Expected output shows a character device with mode crw-rw-rw- (0666). If it does not exist, the fuse3 package and a reboot (or modprobe fuse) will create it.

Volumes Directory

Gershwin Workspace mounts images under /Volumes. This directory must exist with world-writable sticky-bit permissions so that non-root users can create mount points:

sudo mkdir -p /Volumes
sudo chmod 1777 /Volumes

Verify:

stat /Volumes
# Access should be (1777/drwxrwxrwt)

FUSE Configuration

If you need other users (or root) to access a FUSE mount, uncomment user_allow_other in /etc/fuse.conf:

sudo sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf

This is required by MountSystemImage.sh, which passes -o allow_other to squashfuse.

Build-Time Configuration

When building gershwin-workspace from source, configure auto-detects libsquashfs via pkg-config. Confirm detection with:

pkg-config --exists libsquashfs && echo "found" || echo "not found"
pkg-config --cflags --libs libsquashfs

After running ./configure, verify that Workspace/config.h contains:

#define HAVE_SQUASHFS 1

If it shows 0, the library was not found. Ensure libsquashfs-dev is installed and re-run ./configure.

Supported File Extensions

VolumeManager recognises the following extensions for SquashFS images:

.squashfs
.sqsh
.sfs

Unmounting

FUSE mounts under /Volumes can be unmounted with:

fusermount3 -u /Volumes/<mount-name>

Or from within Gershwin Workspace via the volume manager.

Quick Verification

Run the following to confirm everything is in place:

# All required packages installed
dpkg -l squashfuse fuse3 libfuse3-4 libsquashfs-dev squashfs-tools

# FUSE kernel support
test -c /dev/fuse && echo "/dev/fuse OK" || echo "/dev/fuse MISSING"

# fusermount3 available
which fusermount3 && echo "fusermount3 OK" || echo "fusermount3 MISSING (install fuse3)"

# squashfuse available
which squashfuse && echo "squashfuse OK" || echo "squashfuse MISSING"

# /Volumes exists with correct permissions
test -d /Volumes && echo "/Volumes OK" || echo "/Volumes MISSING"

# libsquashfs detectable by pkg-config (build-time)
pkg-config --exists libsquashfs && echo "libsquashfs OK" || echo "libsquashfs MISSING"

Most common issue: The fuse3 package is not installed. Without it, fusermount3 is unavailable and squashfuse cannot register mounts — even though the library, kernel module, and /dev/fuse are all present.