Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zerotier/toss
Dead simple LAN file transfers from the command line
https://github.com/zerotier/toss
Last synced: 3 months ago
JSON representation
Dead simple LAN file transfers from the command line
- Host: GitHub
- URL: https://github.com/zerotier/toss
- Owner: zerotier
- License: other
- Created: 2017-05-04T21:49:36.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-08-27T13:04:39.000Z (about 3 years ago)
- Last Synced: 2024-03-27T03:59:58.741Z (8 months ago)
- Language: C
- Size: 20.5 KB
- Stars: 394
- Watchers: 17
- Forks: 23
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
toss: dead simple command line file transfer
======Toss is a convenient ultra-minimal command line tool to send files over LAN, WiFi, and [virtual networks](https://www.zerotier.com/).
## Examples
### Toss a file between two terminal windows
Sender:
# toss nginx.conf
nginx.conf/rpyaaaaaaaaaatevqcopx2r56xbo4bakxpjzgeh5qblmfyq4ertt3gmtnncrxyouReceiver:
$ catch nginx.conf/rpyaaaaaaaaaatevqcopx2r56xbo4bakxpjzgeh5qblmfyq4ertt3gmtnncrxyou
catch: catching nginx.conf (19605 bytes)
catch: 10.187.211.147/35824 connected, reading... wrote 19605 bytes to: nginx.conf### Toss a file to your team
# toss debug-output.log
debug-output.log/vd4qaaaaaaaaabqprfnhdzwnq3r2gbakxpjzgeh5qblmfyq4ertt3gmtnncrxyouThen paste the token into a chat system like IRC, Slack, etc.
### Stream a huge archive between systems
Sender:
# tar -czf - /usr | toss -
ruz7777777777777tu3pjur2yqhtmbakxpjzgeh5qblmfyq4ertt3gmtnncrxyouReceiver:
$ catch ruz7777777777777tu3pjur2yqhtmbakxpjzgeh5qblmfyq4ertt3gmtnncrxyou - | tar -tzf -
### Toss the output of a command to a team member
$ ps aux | toss -
zmr7777777777777grxowcyqr4w3gbakxpjzgeh5qblmfyq4ertt3gmtnncrxyouThen paste the token into a chat and your team member can do this:
$ catch zmr7777777777777grxowcyqr4w3gbakxpjzgeh5qblmfyq4ertt3gmtnncrxyou -
... and see the output of your `ps aux` command.
## Description
The `toss` program outputs a token generated from a random local TCP port, the size of the file you're sending, a hash of the file's contents (unless it's a pipe), and all the available IP addresses on all the interfaces in your system. It then listens for `catch` to connect and if presented with the correct claim token streams the file. If its input is a file it will continue to service `catch` requests one after the other (not concurrently) until it is terminated with CTRL+C or a kill signal. For pipes it terminates when the pipe closes.
The `catch` program takes a `toss` token and then attempts to connect to all the IP addresses specified in it. If connection is successful it listens for a hello message (based on the hashed token) and if this is correct sends a claim message (a different version of the hashed token). If this exchange succeeds `toss` will send the file and `catch` will receive it.
To toss a pipe, use `toss -`. To catch something and pipe it to standard output, use `catch -`. Both programs send status and error messages to standard error.
The token can include a file name (the part before the slash) but this is optional. If this is not present `catch` will name the file based on its hash or the output file name provided on the command line.
Transfers are done using TCP over ports between 30000 and 65535. You may have to configure your local firewall to allow this, or at least to allow it between certain IP addresses.
Toss will work across the open Internet if no firewalls are in the way but it's mostly intended for LANs, WiFi networks, and [ZeroTier virtual networks](https://www.zerotier.com/) (plug, plug! we wrote this!). This little utility serves as an example of how easy things are if devices can communicate directly.
## Security
Toss does no encryption and authentication is based on the token alone. Files are checked against a 64-bit hash, but pipes rely on TCP CRC checking alone. If you are transferring sensitive information over an un-trusted insecure network we highly recommend encrypting it with a real crypto tool like GPG or a similar.
The `catch` command prioritizes private IP addresses and only tries globally scoped IPs after all attempts to use private ones have failed.
## Building
On Linux, Mac, and BSD just type `make`. The source is self-contained and there are no dependencies.
Some work has been done to prepare for a Windows port but this is incomplete. Pull requests are welcome.
## License
MIT license.
## Changes
* Version 1.1: add a DESTDIR to `make install` and make toss favor ZeroTier and tun/tap interfaces over physical ones. It just lists them first so catch will try them first.
* Version 1.0: initial release!