Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
decoyjoe committed Dec 14, 2024
1 parent e2eb45c commit 29fab09
Showing 1 changed file with 11 additions and 46 deletions.
57 changes: 11 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@

# sanoid-portable

Run [Sanoid](https://github.com/jimsalterjrs/sanoid) without installing any dependencies.
Run [Sanoid, Syncoid, and Findoid](https://github.com/jimsalterjrs/sanoid) without installing any dependencies.

## Summary

*sanoid-portable* is a self-contained, portable build of the [Sanoid](https://github.com/jimsalterjrs/sanoid) ZFS
snapshot management tool. Built using [APPerl (Actually Portable Perl)](https://computoid.com/APPerl/), this
self-contained, portable binary encompasses the Perl runtime, all required Perl dependencies, and the Sanoid script
itself. This enables you to run Sanoid on any Linux or FreeBSD system without needing to install additional Perl
self-contained, portable binary encompasses the Perl runtime, all required Perl dependencies, and the
Sanoid/Syncoid/Findoid scripts themselves. This enables you to run Sanoid on any Linux or FreeBSD system without needing
to install additional Perl
dependencies or configure the system's Perl environment.

This is useful if you'd like to use Sanoid on an appliance-like storage system, such as TrueNAS, where standard package
installations are restricted or non-ideal.

## Installation

Download the latest version of sanoid-portable from the GitHub releases and make it executable:
- Download the latest version of sanoid-portable from the GitHub releases and make it executable.
- [***Assimilate***](https://github.com/jart/cosmopolitan/blob/3.9.7/tool/cosmocc/README.md#installation) the
sanoid-portable binary to transform it into a native binary for the current system.
- Create symbolic links for each tool you plan to use (sanoid-portable uses the invoking command name (`argv[0]`) to
determine which tool it runs.

```console
wget https://github.com/decoyjoe/sanoid-portable/releases/latest/download/sanoid-portable
chmod +x sanoid-portable
```

Create symbolic links for each tool you plan to use (sanoid-portable uses the invoking command name (`argv[0]`) to
determine its behavior):

```console
sh ./sanoid-portable --assimilate # Transforms portable into a native binary
ln -s sanoid-portable sanoid
ln -s sanoid-portable syncoid
ln -s sanoid-portable findoid
Expand All @@ -47,41 +47,6 @@ documentation](https://github.com/jimsalterjrs/sanoid) for configuration instruc

### Compatibility Notes

#### ZSH / fish

If you're using the ZSH or fish shells and you get an error such as `zsh: exec format error: sanoid-portable`, then you
need to update your shell. This issue is patched in [ZSH
5.9+](https://github.com/zsh-users/zsh/commit/326d9c203b3980c0f841bc62b06e37134c6e51ea) and [fish
3.3.0+](https://github.com/fish-shell/fish-shell/commit/0048730a67a5e70cafce1fb725a4b28001d924ac).

If you can't update your shell, then you ***must*** run sanoid-portable from a Thompson Shell-compatible shell such as
`bash`.

#### Ubuntu

On Ubuntu you may get an error such as `run-detectors: unable to find an interpreter` or `File does not contain a valid
CIL image.` This is because Ubuntu's built-in "MZ" binfmt interpreter "helpfully" tries to run the binary with Wine.

You have two options to fix this:

- [***Assimilate***](https://github.com/jart/cosmopolitan/blob/3.9.7/tool/cosmocc/README.md#installation) the
sanoid-portable binary to transform it into a native ELF binary at the expense of making it no longer portable, i.e.
it will henceforth only run on Linux platforms:

```console
sh ./sanoid-portable --assimilate # Transforms the binary into ELF
./sanoid-portable --help
```

- OR

- Add a new binfmt entry that matches APE's ([Actually Portable Executable](https://justine.lol/ape.html))'s magic number to avoid execution by Ubuntu's built-in "MZ" binfmt interpreter:

```console
sudo update-binfmts --install APE /bin/sh --magic MZqFpD
./sanoid-portable --help
```

#### Windows Subsystem for Linux (WSL)

In WSL you need to disable the [`WSLInterop`](https://learn.microsoft.com/en-us/windows/wsl/filesystems#disable-interoperability) binfmt interpreter that's used to launch Windows binaries from Linux:
Expand Down Expand Up @@ -111,7 +76,7 @@ The executable gets built to `output/sanoid-portable`.

## Credits

We stand on the shoulders of giants.
We stand on the shoulders of giants. Thanks to:

- [jimsalterjrs/sanoid](https://github.com/jimsalterjrs/sanoid) for the excellent ZFS snapshot management tool.
- [G4Vi/Perl-Dist-APPerl](https://github.com/G4Vi/Perl-Dist-APPerl) for the tooling to create single-binary portable
Expand Down

0 comments on commit 29fab09

Please sign in to comment.