sysadminmatmoz
fcbd6514cc
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.
131 lines
2.9 KiB
Markdown
131 lines
2.9 KiB
Markdown
# BackTunnel – Secure Reverse SSH Folder Sharing Toolkit
|
||
|
||
**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
|
||
|
||
### 1. Accessor: Prepare your key (one-time)
|
||
```bash
|
||
backtunnel-keys print
|
||
```
|
||
Send the printed public key to the sharer.
|
||
|
||
### 2. Sharer: Start sharing and authorize the accessor
|
||
```bash
|
||
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.
|
||
|
||
### 3. Accessor: Mount the shared folder
|
||
```bash
|
||
backtunnel-access '/home/sharer/Documents' from alice@remotehost -p 2222 -m ~/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
|
||
|
||
`~/.config/backtunnel/profiles.ini`:
|
||
```ini
|
||
[default]
|
||
tunnel_port=2222
|
||
invite=true
|
||
invite_mount=$HOME/remote-rssh
|
||
|
||
[work]
|
||
user=alice
|
||
host=vps.example.com
|
||
tunnel_port=4422
|
||
```
|
||
Usage:
|
||
```bash
|
||
backtunnel-share ~/reports with @work for 6h -i --allow-known alice
|
||
```
|
||
|
||
---
|
||
|
||
## 🖥️ Dolphin Integration
|
||
|
||
- **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
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Install
|
||
|
||
### From source
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
make init # copy example profiles.ini
|
||
```
|
||
|
||
### Arch Linux
|
||
```bash
|
||
makepkg -si
|
||
```
|
||
|
||
Uninstall:
|
||
```bash
|
||
sudo bash scripts/uninstall.sh
|
||
# or with purge of defaults
|
||
sudo PURGE=1 bash scripts/uninstall.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Documentation
|
||
```bash
|
||
man backtunnel
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 License
|
||
GNU GPL v3.0
|
||
© 2025 LUXIM d.o.o., Slovenia – Matjaž Mozetič
|