https://github.com/wcampbell0x2a/backhand
Library and binaries for the reading, creating, and modification of SquashFS file systems
https://github.com/wcampbell0x2a/backhand
compression filesystem linux rust squashfs
Last synced: about 2 months ago
JSON representation
Library and binaries for the reading, creating, and modification of SquashFS file systems
- Host: GitHub
- URL: https://github.com/wcampbell0x2a/backhand
- Owner: wcampbell0x2a
- License: apache-2.0
- Created: 2022-07-19T03:25:16.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-08-07T03:31:58.000Z (over 1 year ago)
- Last Synced: 2024-08-09T10:02:19.504Z (over 1 year ago)
- Topics: compression, filesystem, linux, rust, squashfs
- Language: Rust
- Homepage:
- Size: 1.53 MB
- Stars: 111
- Watchers: 4
- Forks: 8
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE-APACHE
Awesome Lists containing this project
README
backhand
===============================
[
](https://github.com/wcampbell0x2a/backhand)
[
](https://crates.io/crates/backhand)
[
](https://docs.rs/backhand)
[
](https://github.com/wcampbell0x2a/backhand/actions?query=branch%3Amaster)
[
](https://app.codecov.io/gh/wcampbell0x2a/backhand)
Library and binaries for the reading, creating, and modification
of [SquashFS](https://en.wikipedia.org/wiki/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](https://docs.rs/backhand/latest/backhand/#features), 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](https://docs.rs/backhand/latest/backhand/kind/index.html) 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-backhand` through the use of the `--kind` option.
#### Squashfs Support
| 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` |
## Library
*Compiler support: requires rustc 1.86+*
Add the following to your `Cargo.toml` file:
```toml
[dependencies]
backhand = "0.25.0"
```
#### Target Support
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` | ✓ | |
### Reading/Writing/Modifying Firmware
```rust,no_run
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();
```
## Binaries
*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](https://github.com/wcampbell0x2a/backhand/releases/latest).
See ``--help`` for more information.
#### Target Support
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` | ✓ | ✓ |
### unsquashfs-backhand
```no_test
tool to uncompress, extract and list squashfs filesystems
Usage: unsquashfs-backhand [OPTIONS] [FILESYSTEM]
Arguments:
[FILESYSTEM] Squashfs file
Options:
-o, --offset 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 Extract to [PATHNAME] [default: squashfs-root]
-i, --info Print files as they are extracted
--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(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 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
```
### add-backhand
```no_test
tool to add a file or directory to squashfs filesystems
Usage: add-backhand [OPTIONS]
Arguments:
Squashfs input image
Path of file once inserted into squashfs
Squashfs output image path
Options:
-d, --dir Create empty directory
-f, --file Path of file to read, to write into squashfs
--mode Override mode read from
--uid Override uid read from
--gid Override gid read from
--mtime Override mtime read from
--pad-len Custom KiB padding length
--no-compression-options Don't emit compression options
-h, --help Print help
-V, --version Print version
```
### replace-backhand
```no_test
tool to replace files in squashfs filesystems
Usage: replace-backhand [OPTIONS]
Arguments:
Squashfs input image
Path of file to read, to write into squashfs
Path of file replaced in image
Squashfs output image
Options:
--pad-len Custom KiB padding length
--no-compression-options Don't emit compression options
-h, --help Print help
-V, --version Print version
```
## Development
All patches/merge requests are welcome! See the development guide for more details.
[DEVELOPMENT.md](DEVELOPMENT.md).
## Performance
See [BENCHMARK.md](BENCHMARK.md).
## Testing
See [backhand-test](backhand-test/README.md).