nfltr-send

The sending machine prints an address; whoever holds it receives. The files go from one machine to the other, directly when the two networks allow it and through the relay otherwise, encrypted end to end either way.


What it does

nfltr-send is an open-source command (Apache-2.0), github.com/nfltr/send, built on the relay's public client SDK.

The resume, commit and end-of-transfer rules are checked TLA+ models in the repository's spec/.

Install

Release binaries for Linux, macOS and Windows on amd64 and arm64 are on the releases. Each release carries SHA256SUMS, the SHA-256 of every binary, and SHA256SUMS.sshsig, its signature by nfltr-send's own release key in the repository's release/allowed_signers, Ed25519 SHA256:TqSS4Ad7mrwaNN6vZmr2liyFAK8Gk5AGDg0KH0evc9I. Checking both needs ssh-keygen from OpenSSH 8.1 or later (ssh -V prints the version); its Good "nfltr-release" signature line names the key's fingerprint, which is the one above. The commands take the latest release; download/<version> in place of latest/download takes another.

Linux (on arm64, nfltr-send_linux_arm64):

$ f=nfltr-send_linux_amd64; u=https://github.com/nfltr/send/releases/latest/download
$ for x in $f SHA256SUMS SHA256SUMS.sshsig; do curl -fsSLO $u/$x; done
$ curl -fsSLO https://raw.githubusercontent.com/nfltr/send/main/release/allowed_signers
$ ssh-keygen -Y verify -f allowed_signers -I nfltr-release -n nfltr-release -s SHA256SUMS.sshsig < SHA256SUMS
$ grep " $f\$" SHA256SUMS | sha256sum -c && mkdir -p ~/.local/bin && install -m 755 $f ~/.local/bin/nfltr-send

macOS (on Intel, nfltr-send_darwin_amd64), which checks the sum with shasum:

$ f=nfltr-send_darwin_arm64; u=https://github.com/nfltr/send/releases/latest/download
$ for x in $f SHA256SUMS SHA256SUMS.sshsig; do curl -fsSLO $u/$x; done
$ curl -fsSLO https://raw.githubusercontent.com/nfltr/send/main/release/allowed_signers
$ ssh-keygen -Y verify -f allowed_signers -I nfltr-release -n nfltr-release -s SHA256SUMS.sshsig < SHA256SUMS
$ grep " $f\$" SHA256SUMS | shasum -a 256 -c && mkdir -p ~/.local/bin && install -m 755 $f ~/.local/bin/nfltr-send

~/.local/bin is where nfltr's installer puts nfltr; add it to PATH if it is not there yet.

Windows, in PowerShell (on arm64, nfltr-send_windows_arm64.exe):

PS> $ProgressPreference = "SilentlyContinue"; $f = "nfltr-send_windows_amd64.exe"; $u = "https://github.com/nfltr/send/releases/latest/download"
PS> foreach ($x in $f, "SHA256SUMS", "SHA256SUMS.sshsig") { Invoke-WebRequest "$u/$x" -OutFile $x }
PS> Invoke-WebRequest "https://raw.githubusercontent.com/nfltr/send/main/release/allowed_signers" -OutFile allowed_signers
PS> cmd /c "ssh-keygen -Y verify -f allowed_signers -I nfltr-release -n nfltr-release -s SHA256SUMS.sshsig < SHA256SUMS"; if ($LASTEXITCODE) { throw "SHA256SUMS is not signed by the release key" }
PS> $sum = (Select-String -Path SHA256SUMS -SimpleMatch " $f").Line.Split(" ")[0]
PS> if ((Get-FileHash $f -Algorithm SHA256).Hash -ne $sum) { throw "$f does not match SHA256SUMS" }
PS> New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null; Move-Item -Force $f "$HOME\bin\nfltr-send.exe"

cmd /c hands SHA256SUMS to ssh-keygen byte for byte, which a PowerShell pipe does not; add $HOME\bin to PATH if it is not there yet.

With Go, built from source instead of the signed binary:

$ go install github.com/nfltr/send/cmd/nfltr-send@latest

The sender's relay is --relay when given, else $NFLTR_SEND_RELAY, else the one nfltr config set-relay saved (with its pin), else nfltr.xyz. Only the saved relay's address and pin are read, never an account or key. The receiver takes its relay from the address: receive refuses --relay and --relay-http (exit 1) and ignores $NFLTR_SEND_RELAY.

nfltr-send version prints the version, commit and Go version; -h on any command prints its usage and exits 0.

Examples

Each example uses the commands and flags of the repository's README, and its tests run each against a relay started in the test.

A file

The sender writes the address to a file and keeps serving; the receiver reads it on standard input, never from the command line:

sender$ nfltr-send send big.bin > address
serving 1 file, 1073741824 bytes; give the receiver this address (a secret: whoever holds it can receive):
receiver$ nfltr-send receive --to ~/Downloads < address
received 1 file, 1073741824 bytes in 4.5 s (237 MB/s), path direct

Copy the file address to the other machine over a channel you trust. Whoever holds it can receive.

A directory, served once

--once ends the sender after the first complete transfer:

sender$ nfltr-send send --once photos/ > address
receiver$ nfltr-send receive --to ~/Pictures < address

In a script

--json ends a receive with one JSON line on standard error: on success the totals (files, bytes, written, seconds, first_byte_s, sessions) and each path the transfer used (paths), on failure the exit status, its code (not_found, refused, unreachable, reset, ... from the table below) and the error:

receiver$ nfltr-send receive --json --to ~/Downloads < address

A private relay

A sender on a private relay pins its certificate with --cert-sha256 (or $NFLTR_RELAY_CERT_SHA256, or the pin nfltr config set-relay saved); the receiver passes the same pin to check the relay the address names:

sender$ nfltr-send send --relay relay.example.com:443 --cert-sha256 <sha256> big.bin > address
receiver$ nfltr-send receive --cert-sha256 <sha256> --to ~/Downloads < address

--direct off on either end keeps the transfer relayed (a sender needs its machine certificate for that); the default, --direct on, takes a direct path when the networks allow one.

After a cut

A receive that was cut (a machine slept, a network dropped) resumes by itself, up to --tries sessions (default 10). Run the same receive again later and it continues from what is already in its hidden .nfltr-send-* directory: each kept part is verified against the root, and only the chunks missing or not verifying are sent again.

receiver$ nfltr-send receive --to ~/Downloads < address

Exit codes

nfltr-send and nfltr-pipe share one table, so a number means the same in both; code is the name receive --json gives it.

exit code meaning
0 done: every file committed (receive), or the --once transfer ended (send)
1 usage bad flags, address or configuration, before any connection
2 auth the relay refused this machine's certificate, or serves no address without an account
3 not_found nothing serves at the address: the sender stopped, never ran, or its --once transfer ended
4 refused a name exists in --to, the sender is busy or refused the commit, no protocol version in common, or the relay's limits
5 unreachable the relay or the sender was not reached in time, or the relay's certificate was refused
6 reset the last of --tries sessions was cut, or the receive was stopped (receive the address again to resume)
7 e2ee_pin_mismatch the sender's key is not the address's
9 balance_exhausted the serving account's balance is exhausted
10 e2ee_client_refused the sender refused this receive's proof
12 direct_required no direct path to a sender serving with no account
130, 143 send stopped by SIGINT or SIGTERM

A receive tries another session after 3, 5 and 6, up to --tries; every other failure ends it at once.

Who needs an account

The receiving machine needs none. The sending machine needs none either, while the bytes can go peer to peer:

Compatibility

From v0.1.8 the flags, variables, exit codes, --json keys and address format above are nfltr-send's v1 contract: later releases keep them, and a sender and a receiver of different releases work together, both ways. The two ends agree on a transfer protocol version at the start of each session, the highest both speak; an end with none in common exits 4. The full contract is the repository's docs/v1-contract.md.

Reliability, measured

A rerunnable matrix and soak on one Linux machine: a private relay, a sender and a receiver in their own network namespaces, with the rate, round trip and loss set for the direct and the relayed path alike. Each transfer is judged by its exit codes and by the received tree against the sent one: every name, type and SHA-256, nothing missing, nothing extra.

The full tables, the defects and how to rerun it are in the reliability report; transfers of 10 GiB, 100 GiB and 100,000 files between regions are in the scale report.