Send Files and Messages Between Machines

Move a file or a message from one of your machines to another, wherever they are. Nothing gets a public link: the other machine serves a named service, admits only machines of your organisation's group, and every byte is end-to-end encrypted between the two machines.


Goal

From your laptop: send report.txt to work-laptop, send it a message, and run one command there.

Prerequisites

A service cat serve starts is reached as <machine>.<agent>/<service>. Its agent is the serving machine's name unless --agent says otherwise, so the service inbox on work-laptop is work-laptop.work-laptop/inbox. A nfltr http or nfltr share on the same machine does not take it: their agents are their own (work-laptop-http, work-laptop-share). Each cat serve process is its own agent: a second cat serve of the same agent on the machine is refused (exit 14) and names the running one. To run two at once, give one of them another --agent (nfltr cat serve clip --agent clip ... is work-laptop.clip/clip), or run both services in one nfltr up -c FILE; --replace hands the agent to the new process, and the running one exits 13. nfltr services and nfltr machines list show what is online.

1. Send a file

On work-laptop, receive one transfer into ~/Downloads, admitting the group ops:

$ nfltr cat serve inbox --recv ~/Downloads --once --allow-group ops

On your laptop, send it:

$ echo "Q3 numbers: 42" > report.txt
$ nfltr cat cp report.txt work-laptop.work-laptop/inbox

cat cp takes any number of files and directories and sends them as one stream; a directory keeps its tree (nfltr cat cp report.txt ./data/ work-laptop.work-laptop/inbox). work-laptop writes them under ~/Downloads and, with --once, exits after the one transfer; without it, it keeps receiving.

The receiver writes nothing outside its directory: a name with .., an absolute path, a symlink, a hard link or a device refuses the transfer. A name that already exists there refuses the whole transfer, nothing is replaced, and cat cp exits 4 (refused). cat cp sends only to a cat serve --recv service, and only end to end encrypted: it has no --plain.

2. Send a message

On work-laptop, serve one session on the terminal (stdin and stdout), like nc -l:

$ nfltr cat serve chat --allow-group ops

On your laptop, open it:

$ nfltr cat pipe work-laptop.work-laptop/chat

What you type on one end appears on the other, both ways. Ctrl+D ends what one end sends; the session closes once both ends have, or when either end stops with Ctrl+C. Data piped in works the same way: echo '{"cmd":"status"}' | nfltr cat pipe work-laptop.work-laptop/chat. Without --allow-group a service is not end-to-end encrypted, the relay can read the session, and cat pipe reaches it only with --plain.

3. Run a command on the other machine

--exec runs one fixed command for each session: the session is its stdin and stdout, its stderr goes to the server's log. The command is the argv after --, run without a shell; the client adds no arguments. It is off unless you give it, needs --allow-group, runs one session at a time (--max-sessions 1) and stops a session after 60 seconds (--session-timeout 60s). The command's environment carries no relay key or other nfltr credential.

On work-laptop (a Mac), put whatever arrives on its clipboard:

$ nfltr cat serve clip --exec --allow-group ops -- pbcopy

On your laptop:

$ pbpaste | nfltr cat pipe work-laptop.work-laptop/clip

cat pipe exits 0 when the command exits 0. A command that exits non-zero, or that --session-timeout stops, ends cat pipe with exit 11 (remote_failed); its error event on stderr carries the command's exit_status. To read from the other machine instead, serve a command that prints (-- cat /var/log/app.log) and cat pipe it.

Clean up

cat serve --recv --once has already exited; so has cat serve chat, after its one session. Stop the others with Ctrl+C.

Without an organisation: a capability address

--address serves a service under a capability address, a long nf1… string that names the relay, pins the service's key and carries a secret. Whoever holds it opens the service with no account and no machine certificate, end to end encrypted: the relay sees neither the secret nor the bytes. It works with stdio, --forward, --exec and --recv, in place of --allow-group.

On work-laptop:

$ nfltr cat serve inbox --recv ~/Downloads --address
Address of work-laptop/inbox (anyone who has it can open the service; keep it secret):
nf1aeh...

Anyone you give the address to, on any machine with the nfltr CLI, keeps it in a file only they can read and names that file (- reads it from stdin, except for cat pipe, whose stdin is the session):

$ (umask 077 && cat > ~/inbox.addr)     # paste the address, then Ctrl+D
$ nfltr cat cp report.txt --address-file ~/inbox.addr
$ nfltr cat pipe --address-file ~/inbox.addr < request.bin > answer.bin
$ nfltr cat forward --address-file ~/db.addr --listen 127.0.0.1:5432

An address on the command line is refused: every user of the machine can read a command line (ps, /proc/<pid>/cmdline), and whoever holds the address can open the service.

The address is printed once, when it is made, and kept in a file only you can read beside the nfltr config, so a restart serves the same address; --show-address prints it again. Treat it like a password: send it over a channel you trust. To revoke it, serve the service with --new-address: the old address stops working at once, and you hand out the new one. Only the holder of the service's key can make the relay serve an address, so a client holding the address cannot take it over or block it. An address made by an older nfltr, before addresses were bound to the service's key, is no longer served: cat serve --address refuses it and names --new-address; serve with it once and hand out the new address. Sessions to the address are charged to the serving machine's account, and the relay limits how many each address and each client source may open.

Serving with no account

On a relay that takes it (off on nfltr.xyz for now), cat serve --address and an nfltr up service with address: run with no key and no login. Such an address carries its bytes only on a direct path between the two machines: the relay carries the signalling (a few kilobytes) and nothing else. Clients take a direct path by default (--direct=off, direct: off on a connect: mapping, keeps a session relayed):

$ nfltr cat cp report.txt --address-file ~/inbox.addr

Where no direct path forms (a symmetric NAT on both sides, UDP blocked), or with --direct=off, the client exits 12 with "code":"direct_required" and nothing is written. The serving machine then serves the address with an account (nfltr config login), and its sessions may go through the relay. --direct off with no account is refused at start.

If it goes wrong

You seeMeaning and fix
exit 3, "code":"not_found"Nothing serves that address. Start nfltr cat serve on the other machine first and check the target: <machine>.<agent>/<service>, the agent being the serving machine's name unless it gave --agent.
cat cp exit 4, "code":"refused"The receiver refused the transfer: a name already exists in its directory, or a name would leave it. Nothing was written; its log names the entry. Exit 4 also means the target is not a cat serve --recv service.
cat cp exit 6, "code":"reset"The transfer ended before the receiver answered that it landed: cat cp was stopped (Ctrl-C, SIGTERM) or the session was cut. Nothing was written to the receiver's directory; send again.
exit 4, takes end-to-end encrypted sessions only: open them from a machine of the agent's organisationThis machine is not enrolled: nfltr org join.
exit 10, e2ee_client_refusedThe service refused this machine's certificate: not in the group it admits, revoked or expired. The service's log names which.
nf1…: exit 1The address has a typo (its checksum fails), or --server or your saved relay names another relay than the address's: drop --server.
nf1…: exit 3, "code":"not_found"Nothing serves that address now: its cat serve --address is stopped, or it was replaced with --new-address, or it was made by an older nfltr and not yet replaced.
nf1…: exit 4, "code":"refused"The relay's limit on sessions of this address, or from your network, was reached. Try again later.
nf1…: exit 12, "code":"direct_required"The address is served with no account, so its bytes go only on a direct path, and none formed (or --direct=off was given). Drop --direct=off, or have the serving machine serve it with an account (nfltr config login).
nf1…: exit 7 or 10The server is not the address's (7), or it refused the address's secret (10): the address was altered. Ask for it again.
exit 11, "code":"remote_failed"The --exec command exited non-zero (exit_status) or ran past --session-timeout. Its stderr is in the server's log.
cat serve, http, share or up: exit 14, is already served on this machine byAnother process on this machine serves that agent. Give this one another --agent, serve both from one nfltr up -c FILE, or pass --replace to take the agent over.
cat serve or up: exit 13, another process took the agent overA cat serve --replace or up --replace took the agent over, or the same machine certificate connected it from another machine (a copied config: give each machine its own enrolment).
this session was replaced by a newer one with the same agent ID and keyBoth machines run under the same name with the same key. Give each machine its own key.

Next