209 lines
4.0 KiB
Markdown
209 lines
4.0 KiB
Markdown
# BackTunnel – Secure Reverse SSH Folder Sharing Toolkit
|
||
|
||
**BackTunnel** lets you share and mount folders between Linux machines behind NAT or firewalls using just two friendly commands.
|
||
No central servers. No cloud uploads. Temporary, peer-to-peer, SSH-based.
|
||
|
||
---
|
||
|
||
## ⚡ Quick Start (3 steps)
|
||
|
||
1. **On the sharing machine (server):**
|
||
|
||
```bash
|
||
backtunnel-share ~/Documents with user@remotehost for 2h -i
|
||
```
|
||
|
||
→ Opens a tunnel for 2 hours and prints an **invite**.
|
||
|
||
2. **Send the invite** (via chat, email, QR). It looks like:
|
||
|
||
```bash
|
||
backtunnel-auth-setup -p 2222 user@localhost
|
||
backtunnel-access '/home/alice/Documents' from user@remotehost -p 2222 -m "$HOME/remote-rssh"
|
||
```
|
||
|
||
3. **On the accessing machine (client):**
|
||
|
||
```bash
|
||
mkdir -p ~/remote-rssh
|
||
backtunnel-auth-setup -p 2222 user@localhost
|
||
backtunnel-access '/home/alice/Documents' from user@remotehost -p 2222 -m ~/remote-rssh
|
||
```
|
||
|
||
→ Folder is mounted at `~/remote-rssh`.
|
||
|
||
Unmount afterwards with:
|
||
|
||
```bash
|
||
fusermount -u ~/remote-rssh
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Why BackTunnel?
|
||
|
||
* **Works behind NAT/firewalls**: reverse SSH tunnels, no port forwarding needed.
|
||
* **Private by design**: no third-party relays or cloud.
|
||
* **Temporary by default**: shares auto-stop after chosen duration.
|
||
* **Simple invites**: send one-liners (or QR codes) to colleagues.
|
||
* **Safe**: restricted SFTP-only keys ensure no shell access.
|
||
* **Desktop integration**: right-click folders in Dolphin to share or access.
|
||
|
||
---
|
||
|
||
## ✨ Commands
|
||
|
||
### `backtunnel-share` — start a share
|
||
|
||
*(sharing side)*
|
||
|
||
```bash
|
||
backtunnel-share /path/to/folder with user@remotehost for <duration> [options]
|
||
```
|
||
|
||
**Duration formats:** `30m`, `2h`, `1d`
|
||
**Key options:**
|
||
|
||
* `-p, --tunnel-port <PORT>` — Remote port (default: `2222`)
|
||
* `-l, --local-ssh-port <PORT>` — Local SSHD port (default: `22`)
|
||
* `-i, --invite` — Print a ready-to-copy **invite**
|
||
* `--invite-mount <PATH>` — Suggested mount point (default: `~/remote-rssh`)
|
||
* `--qr` — Show invite as QR code
|
||
|
||
---
|
||
|
||
### `backtunnel-access` — mount a share
|
||
|
||
*(accessing side)*
|
||
|
||
```bash
|
||
backtunnel-access /path/to/folder from user@remotehost [options]
|
||
```
|
||
|
||
**Options:**
|
||
|
||
* `-p, --port <PORT>` — Remote tunnel port (default: `2222`)
|
||
* `-m, --mount-point <PATH>` — Local mount point (default: `~/remote-rssh`)
|
||
|
||
Unmount with:
|
||
|
||
```bash
|
||
fusermount -u ~/remote-rssh
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 Profiles
|
||
|
||
Simplify frequent shares with `~/.config/backtunnel/profiles.ini`.
|
||
Example:
|
||
|
||
```ini
|
||
[default]
|
||
tunnel_port=4422
|
||
invite_mount=$HOME/shared
|
||
|
||
[work]
|
||
user=alice
|
||
host=vps.example.com
|
||
tunnel_port=4423
|
||
```
|
||
|
||
Use with:
|
||
|
||
```bash
|
||
backtunnel-share ~/reports with @work for 6h -i
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 Security
|
||
|
||
* **Restricted keys**: usable only through the tunnel (127.0.0.1).
|
||
* **SFTP-only**: enforced with `internal-sftp,restrict`.
|
||
* **Temporary**: ends when the tunnel closes.
|
||
|
||
---
|
||
|
||
## 🖥️ Dolphin Integration
|
||
|
||
After install, Dolphin menus appear:
|
||
|
||
* **Share via BackTunnel…** — GUI wizard for remote, duration, ports, invite.
|
||
* **Access via BackTunnel…** — GUI wizard for remote, port, mount point.
|
||
|
||
Logs:
|
||
|
||
```
|
||
~/.local/state/backtunnel/servicemenu.*.log
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Install
|
||
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
make init # copy example profiles.ini
|
||
```
|
||
|
||
Uninstall:
|
||
|
||
```bash
|
||
sudo bash scripts/uninstall.sh
|
||
```
|
||
|
||
Arch Linux:
|
||
|
||
```bash
|
||
makepkg -si
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Man Page
|
||
|
||
```bash
|
||
man backtunnel
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 License
|
||
|
||
Licensed under **GNU GPL v3.0**
|
||
© 2025 LUXIM d.o.o., Slovenia – Matjaž Mozetič
|
||
|
||
---
|
||
|
||
## 📝 Cheat Sheet (TL;DR)
|
||
|
||
**Start a share:**
|
||
|
||
```bash
|
||
backtunnel-share ~/Documents with user@remotehost for 2h -i
|
||
```
|
||
|
||
**Send this invite to your colleague:**
|
||
|
||
```bash
|
||
backtunnel-auth-setup -p 2222 user@localhost
|
||
backtunnel-access '/home/user/Documents' from user@remotehost -p 2222 -m ~/remote-rssh
|
||
```
|
||
|
||
**On the client:**
|
||
|
||
```bash
|
||
mkdir -p ~/remote-rssh
|
||
backtunnel-auth-setup -p 2222 user@localhost
|
||
backtunnel-access '/home/user/Documents' from user@remotehost -p 2222 -m ~/remote-rssh
|
||
```
|
||
|
||
**Unmount:**
|
||
|
||
```bash
|
||
fusermount -u ~/remote-rssh
|
||
```
|
||
|
||
---
|