Add accessor key authorization and enhance completion logic
Introduce `backtunnel-authorize` for managing restricted SFTP-only keys, and update `backtunnel-share` to support temporary accessor key authorization via `--allow-key` and `--allow-known`. Extend bash completion with profile, accessor, and SSH host suggestions. Revamp README sections to include updated workflows, quick starts, and key management details.
This commit is contained in:
208
README.md
208
README.md
@@ -1,139 +1,95 @@
|
||||
# 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.
|
||||
**BackTunnel** is a lightweight toolkit to share and mount folders between Linux machines behind NAT or firewalls using **reverse SSH tunnels**.
|
||||
No third-party relay, no cloud dependency – just peer-to-peer, temporary, SSH-based access.
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 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:
|
||||
## ⚡ Quick Start
|
||||
|
||||
### 1. Accessor: Prepare your key (one-time)
|
||||
```bash
|
||||
fusermount -u ~/remote-rssh
|
||||
backtunnel-keys print
|
||||
```
|
||||
Send the printed public key to the sharer.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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)*
|
||||
|
||||
### 2. Sharer: Start sharing and authorize the accessor
|
||||
```bash
|
||||
backtunnel-share /path/to/folder with user@remotehost for <duration> [options]
|
||||
backtunnel-share ~/Documents with alice@remotehost for 2h -i --allow-key ./alice.pub
|
||||
```
|
||||
This injects a **temporary, restricted SFTP-only key** and prints an invite.
|
||||
|
||||
**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)*
|
||||
|
||||
### 3. Accessor: Mount the shared folder
|
||||
```bash
|
||||
backtunnel-access /path/to/folder from user@remotehost [options]
|
||||
backtunnel-access '/home/sharer/Documents' from alice@remotehost -p 2222 -m ~/remote-rssh
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **NAT/firewall friendly**: works without port forwarding.
|
||||
- **Temporary by design**: shares auto-expire after a set duration.
|
||||
- **Invite workflow**: sharer sends a one-liner or QR code to accessor.
|
||||
- **Restricted keys**: accessor keys are usable *only* for SFTP via the tunnel and are auto-removed when the share ends.
|
||||
- **Profiles**: save defaults and common remotes in `profiles.ini`.
|
||||
- **Desktop integration**: Dolphin (KDE) service menus for GUI sharing and access.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Commands
|
||||
|
||||
### Sharing
|
||||
```bash
|
||||
backtunnel-share /path/to/folder with user@host for <duration> [options]
|
||||
```
|
||||
- `-p, --tunnel-port` Remote bind port (default: 2222)
|
||||
- `-l, --local-ssh-port` Local sshd port to expose (default: 22)
|
||||
- `-i, --invite` Print invite line
|
||||
- `--qr` Show QR code (requires qrencode)
|
||||
- `--allow-key FILE` Authorize a provided public key
|
||||
- `--allow-known NAME` Authorize a stored key (~/.config/backtunnel/authorized/NAME.pub)
|
||||
|
||||
### Accessing
|
||||
```bash
|
||||
backtunnel-access /path/to/folder from user@host [options]
|
||||
```
|
||||
- `-p, --port` Tunnel port (default: 2222)
|
||||
- `-m, --mount-point` Local mount point (default: ~/remote-rssh)
|
||||
|
||||
---
|
||||
|
||||
## 📁 Profiles
|
||||
|
||||
Simplify frequent shares with `~/.config/backtunnel/profiles.ini`.
|
||||
Example:
|
||||
|
||||
`~/.config/backtunnel/profiles.ini`:
|
||||
```ini
|
||||
[default]
|
||||
tunnel_port=4422
|
||||
invite_mount=$HOME/shared
|
||||
tunnel_port=2222
|
||||
invite=true
|
||||
invite_mount=$HOME/remote-rssh
|
||||
|
||||
[work]
|
||||
user=alice
|
||||
host=vps.example.com
|
||||
tunnel_port=4423
|
||||
tunnel_port=4422
|
||||
```
|
||||
|
||||
Use with:
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
backtunnel-share ~/reports with @work for 6h -i
|
||||
backtunnel-share ~/reports with @work for 6h -i --allow-known alice
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 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:
|
||||
- **Share via BackTunnel…** – GUI dialog for sharer options.
|
||||
- **Access via BackTunnel…** – GUI dialog for accessor options.
|
||||
|
||||
Logs are written to:
|
||||
```
|
||||
~/.local/state/backtunnel/servicemenu.*.log
|
||||
```
|
||||
@@ -142,27 +98,27 @@ Logs:
|
||||
|
||||
## 📦 Install
|
||||
|
||||
### From source
|
||||
```bash
|
||||
sudo bash scripts/install.sh
|
||||
make init # copy example profiles.ini
|
||||
```
|
||||
|
||||
Uninstall:
|
||||
|
||||
```bash
|
||||
sudo bash scripts/uninstall.sh
|
||||
```
|
||||
|
||||
Arch Linux:
|
||||
|
||||
### Arch Linux
|
||||
```bash
|
||||
makepkg -si
|
||||
```
|
||||
|
||||
Uninstall:
|
||||
```bash
|
||||
sudo bash scripts/uninstall.sh
|
||||
# or with purge of defaults
|
||||
sudo PURGE=1 bash scripts/uninstall.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Man Page
|
||||
|
||||
## 📖 Documentation
|
||||
```bash
|
||||
man backtunnel
|
||||
```
|
||||
@@ -170,39 +126,5 @@ man backtunnel
|
||||
---
|
||||
|
||||
## 🧾 License
|
||||
|
||||
Licensed under **GNU GPL v3.0**
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user