BackTunnel/README.md

# 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č