Library and binaries for the reading, creating, and modification of SquashFS file systems.
- Library — Backhand provides an easy way for programmatic analysis of Squashfs images, including the extraction and modification of images.
- Feature Flags — Supported compression and decompression are feature flagged, so your final binary (or
unsquashfs) only needs to include code to extract one type of image. - Unconventional Support — As well as supporting normal linux kernel SquashFS 4.0 and 3.0, we also support the "wonderful world of vendor formats" with a Kind struct. This allows changing the magic bytes, custom compression algorithms, and the Endian-ness of either the Data or Metadata fields. This is controlled from
unsquashfs-backhandthrough the use of the--kindoption.
| Kind | read | write | Feature |
|---|---|---|---|
be_v4_0 | ✓ | ✓ | default |
le_v4_0 | ✓ | ✓ | default |
avm_be_v4_0 | ✓ | ✓ | default |
be_v3_0 | ✓ | v3 | |
le_v3_0 | ✓ | v3 | |
be_v3_0_lzma | ✓ | v3_lzma | |
le_v3_0_lzma | ✓ | v3_lzma | |
netgear_be_v3_0_lzma | ✓ | v3_lzma | |
netgear_be_v3_0_lzma_standard | ✓ | v3_lzma | |
be_v3_0_lzma_swap | ✓ | v3_lzma | |
le_v3_0_lzma_swap | ✓ | v3_lzma |
Compiler support: requires rustc 1.86+
Add the following to your Cargo.toml file:
[dependencies] backhand = "0.25.0"Although additional targets may be supported, only the following have been fully tested or confirmed to build successfully.
| Target | build | test |
|---|---|---|
x86_64-unknown-linux-musl | ✓ | ✓ |
aarch64-unknown-linux-musl | ✓ | ✓ |
arm-unknown-linux-musleabi | ✓ | ✓ |
armv7-unknown-linux-musleabi | ✓ | ✓ |
aarch64-unknown-linux-musl | ✓ | ✓ |
x86_64-apple-darwin | ✓ | ✓ |
x86_64-pc-windows-gnu | ✓ |
use std::fs::File; use std::io::{Cursor, BufReader}; use backhand::{FilesystemReader, FilesystemWriter, NodeHeader}; // read let file = BufReader::new(File::open("file.squashfs").unwrap()); let read_filesystem = FilesystemReader::from_reader(file).unwrap(); // convert to writer let mut write_filesystem = FilesystemWriter::from_fs_reader(&read_filesystem).unwrap(); // add file with data from slice let d = NodeHeader::default(); let bytes = Cursor::new(b"Fear is the mind-killer."); write_filesystem.push_file(bytes, "a/d/e/new_file", d); // add file with data from file let new_file = File::open("dune").unwrap(); write_filesystem.push_file(new_file, "/root/dune", d); // modify file let bytes = Cursor::new(b"The sleeper must awaken.\n"); write_filesystem.replace_file("/a/b/c/d/e/first_file", bytes).unwrap(); // write into a new file let mut output = File::create("modified.squashfs").unwrap(); write_filesystem.write(&mut output).unwrap();Compiler support: requires rustc 1.86+
These are currently under development and are missing features, MR's welcome!
To install, run cargo install backhand-cli --locked, or download from the latest github release.
See --help for more information.
Although additional targets may be supported, only the following have been tested and included in our GitHub releases.
| Target | test | release |
|---|---|---|
x86_64-unknown-linux-musl | ✓ | ✓ |
aarch64-unknown-linux-musl | ✓ | ✓ |
arm-unknown-linux-musleabi | ✓ | ✓ |
armv7-unknown-linux-musleabi | ✓ | ✓ |
aarch64-unknown-linux-musl | ✓ | ✓ |
x86_64-apple-darwin | ✓ | ✓ |
tool to uncompress, extract and list squashfs filesystems Usage: unsquashfs-backhand [OPTIONS] [FILESYSTEM] Arguments: [FILESYSTEM] Squashfs file Options: -o, --offset <BYTES> Skip BYTES at the start of FILESYSTEM [default: 0] -a, --auto-offset Find first instance of squashfs --kind magic -l, --list List filesystem, do not write to DEST (ignores --quiet) -d, --dest <PATHNAME> Extract to [PATHNAME] [default: squashfs-root] -i, --info Print files as they are extracted --path-filter <PATH_FILTER> Limit filesystem extraction [default: /] -f, --force If file already exists then overwrite -s, --stat Display filesystem superblock information (ignores --quiet) -k, --kind <KIND> Kind(type of image) to parse. If not specified, will auto-detect by trying all kinds [possible values: le_v4_0, be_v4_0, le_v3_0, be_v3_0, le_v3_0_lzma, be_v3_0_lzma, netgear_be_v3_0_lzma_standard, netgear_be_v3_0_lzma, avm_be_v4_0] --completions <COMPLETIONS> Emit shell completion scripts [possible values: bash, elvish, fish, powershell, zsh] --quiet Silence all progress bar and RUST_LOG output -h, --help Print help (see more with '--help') -V, --version Print version tool to add a file or directory to squashfs filesystems Usage: add-backhand [OPTIONS] <INPUT_IMAGE> <FILE_PATH_IN_IMAGE> <OUTPUT_IMAGE> Arguments: <INPUT_IMAGE> Squashfs input image <FILE_PATH_IN_IMAGE> Path of file once inserted into squashfs <OUTPUT_IMAGE> Squashfs output image path Options: -d, --dir Create empty directory -f, --file <FILE> Path of file to read, to write into squashfs --mode <MODE> Override mode read from <FILE> --uid <UID> Override uid read from <FILE> --gid <GID> Override gid read from <FILE> --mtime <MTIME> Override mtime read from <FILE> --pad-len <PAD_LEN> Custom KiB padding length --no-compression-options Don't emit compression options -h, --help Print help -V, --version Print version tool to replace files in squashfs filesystems Usage: replace-backhand [OPTIONS] <INPUT_IMAGE> <FILE> <FILE_PATH_IN_IMAGE> <OUTPUT_IMAGE> Arguments: <INPUT_IMAGE> Squashfs input image <FILE> Path of file to read, to write into squashfs <FILE_PATH_IN_IMAGE> Path of file replaced in image <OUTPUT_IMAGE> Squashfs output image Options: --pad-len <PAD_LEN> Custom KiB padding length --no-compression-options Don't emit compression options -h, --help Print help -V, --version Print version All patches/merge requests are welcome! See the development guide for more details. DEVELOPMENT.md.
See BENCHMARK.md.
See backhand-test.