142 lines
4.4 KiB
Markdown
142 lines
4.4 KiB
Markdown
# BackTunnel – Reverse SSH Folder Sharing Toolkit
|
||
|
||
Share and mount folders between Linux machines behind NAT/firewalls using two friendly commands.
|
||
|
||
## ✨ Commands
|
||
|
||
### `backtunnel-share`
|
||
Start a reverse SSH tunnel from the *sharing* machine for a limited time.
|
||
|
||
```bash
|
||
backtunnel-share /path/to/folder with remoteuser:remotehost for <duration> [options]
|
||
# or: remoteuser@remotehost
|
||
```
|
||
|
||
**Duration formats:** `30m`, `2h`, `1d` (passed to `timeout`)
|
||
|
||
**Options**
|
||
- `-p, --tunnel-port <PORT>`: Remote port to expose with `-R` (default: 2222)
|
||
- `-l, --local-ssh-port <PORT>`: Local sshd port to forward to (default: 22)
|
||
- `-i, --invite`: Print a ready-to-copy access command for the remote user
|
||
- `--invite-mount <PATH>`: Suggest mount point in the invite (default: `/mnt/remote-rssh`)
|
||
- `--invite-file <FILE>`: Also write the invite text (including unmount hint) to a file
|
||
- `--qr`: Render the invite as a QR code (requires `qrencode`)
|
||
|
||
**Examples**
|
||
```bash
|
||
# Share for 2h
|
||
backtunnel-share ~/projects with alice@vps.example.com for 2h
|
||
|
||
# Share and print a one-liner invite for chat
|
||
backtunnel-share ~/projects with alice@vps.example.com for 2h -i
|
||
|
||
# Share with custom ports and QR invite
|
||
backtunnel-share ~/projects with alice@vps.example.com for 1d -p 4422 -l 2222 -i --qr
|
||
```
|
||
|
||
The invite will look like this and can be pasted on the remote host:
|
||
```bash
|
||
backtunnel-access '/home/user/projects' from alice@vps.example.com -p 4422 -m '/mnt/remote-rssh'
|
||
```
|
||
|
||
Unmount on the remote side with:
|
||
```bash
|
||
fusermount -u /mnt/remote-rssh
|
||
```
|
||
|
||
### `backtunnel-access`
|
||
Mount a folder from the *remote* side via SSHFS.
|
||
|
||
```bash
|
||
backtunnel-access /path/to/folder from remoteuser:remotehost [options]
|
||
# or: remoteuser@remotehost
|
||
```
|
||
|
||
**Options**
|
||
- `-p, --port <PORT>`: Port on the remote host where the reverse tunnel listens (default: 2222)
|
||
- `-m, --mount-point <PATH>`: Local mount point (default: `/mnt/remote-rssh`)
|
||
|
||
---
|
||
|
||
## 📁 Profiles (named remotes)
|
||
|
||
BackTunnel supports **profiles** to simplify connections. Instead of typing
|
||
`user@host -p PORT -l PORT …` every time, you can define defaults and named remotes in:
|
||
|
||
📖 Example config: see [docs/profiles.ini.example](docs/profiles.ini.example)
|
||
|
||
System-wide default: /etc/backtunnel/profiles.ini (admins can edit)
|
||
Packaged example: /usr/share/backtunnel/profiles.ini
|
||
|
||
---
|
||
|
||
### 🖥️ Dolphin Service Menus
|
||
|
||
Two context actions for Dolphin are installed:
|
||
|
||
- **Share via BackTunnel…** → launches the graphical wrapper `backtunnel-share-gui`, prompting for remote, duration, ports, etc.
|
||
- **Access via BackTunnel…** → now uses the new `backtunnel-access-gui` wrapper, providing dialogs for remote, port, and mount point instead of embedding a complex one-liner.
|
||
|
||
Both wrappers run inside Konsole (or xterm) so you can see live logs, and they honor profile defaults from `~/.config/backtunnel/profiles.ini` (or `/etc`, `/usr/share`).
|
||
|
||
### 🖱️ Dolphin (GUI) Flow — Share with Invite
|
||
|
||
1. **Right-click a folder → “Share via BackTunnel…”**
|
||
2. Enter **Remote** (`user@host` or `user:host`), choose **Duration**, **Tunnel port** (default `2222`), and **Local SSH port** (default `22`).
|
||
3. When prompted:
|
||
- **Print invite line for chat?** → Yes to get a one-liner your colleague can paste.
|
||
- **Show QR code for the invite?** → Yes (requires `qrencode`) to display a terminal QR.
|
||
- **Suggested mount point** → Accept `/mnt/remote-rssh` or set your own.
|
||
4. A terminal opens, shows the **invite** (and QR if selected), and keeps the share open for the chosen duration.
|
||
- Stop early with **Ctrl+C**.
|
||
|
||
**What the remote user does (on the remote host):**
|
||
|
||
```bash
|
||
# Paste the invite you sent them, e.g.:
|
||
backtunnel-access '/path/to/folder' from user@vps.example.com -p 2222 -m '/mnt/remote-rssh'
|
||
# Unmount when done:
|
||
fusermount -u /mnt/remote-rssh # or: umount /mnt/remote-rssh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 Requirements
|
||
- `ssh`, `sshfs`, `timeout`, `konsole`, `kdialog`
|
||
- Optional:
|
||
- `bash-completion`
|
||
- `qrencode` (for QR-code invites)
|
||
|
||
---
|
||
|
||
## 📦 Install
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
```
|
||
Uninstall:
|
||
```bash
|
||
sudo bash scripts/uninstall.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 Release checklist (BackTunnel v1.2.x)
|
||
|
||
1. **Version bump** (if needed) in docs/man where referenced (man page already shows `1.2`).
|
||
2. **Tag the repo**:
|
||
|
||
```bash
|
||
git tag -a v1.2.0 -m "BackTunnel 1.2.0"
|
||
git push --tags
|
||
```
|
||
|
||
## 📖 Man Page
|
||
```bash
|
||
man backtunnel
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 License
|
||
Licensed under **GNU GPL v3.0**. See `LICENSE`.
|