BackTunnel/README.md

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

---