Revamp README for enhanced clarity and usability: streamline commands, add quick start, highlight key features, improve examples, and restructure sections for better organization.
This commit is contained in:
296
README.md
296
README.md
@@ -1,233 +1,168 @@
|
|||||||
# BackTunnel – Reverse SSH Folder Sharing Toolkit
|
# BackTunnel – Secure Reverse SSH Folder Sharing Toolkit
|
||||||
|
|
||||||
Share and mount folders between Linux machines behind NAT/firewalls using two friendly commands.
|
**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.
|
||||||
|
|
||||||
## ✨ Commands
|
---
|
||||||
|
|
||||||
### `backtunnel-share`
|
## ⚡ Quick Start (3 steps)
|
||||||
Start a reverse SSH tunnel from the *sharing* machine for a limited time.
|
|
||||||
|
1. **On the sharing machine (server):**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
backtunnel-share /path/to/folder with remoteuser:remotehost for <duration> [options]
|
backtunnel-share ~/Documents with user@remotehost for 2h -i
|
||||||
# or: remoteuser@remotehost
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Duration formats:** `30m`, `2h`, `1d` (passed to `timeout`)
|
→ Opens a tunnel for 2 hours and prints an **invite**.
|
||||||
|
|
||||||
**Options**
|
2. **Send the invite** (via chat, email, QR). It looks like:
|
||||||
- `-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: `~/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
|
```bash
|
||||||
# Share for 2h
|
backtunnel-auth-setup -p 2222 user@localhost
|
||||||
backtunnel-share ~/projects with alice@vps.example.com for 2h
|
backtunnel-access '/home/alice/Documents' from user@remotehost -p 2222 -m "$HOME/remote-rssh"
|
||||||
|
|
||||||
# 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:
|
3. **On the accessing machine (client):**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
backtunnel-access '/home/user/projects' from alice@vps.example.com -p 4422 -m "$HOME/remote-rssh"
|
mkdir -p ~/remote-rssh
|
||||||
|
backtunnel-auth-setup -p 2222 user@localhost
|
||||||
|
backtunnel-access '/home/alice/Documents' from user@remotehost -p 2222 -m ~/remote-rssh
|
||||||
```
|
```
|
||||||
|
|
||||||
Unmount on the remote side with:
|
→ Folder is mounted at `~/remote-rssh`.
|
||||||
|
|
||||||
|
Unmount afterwards with:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
fusermount -u ~/remote-rssh
|
fusermount -u ~/remote-rssh
|
||||||
```
|
```
|
||||||
|
|
||||||
### `backtunnel-access`
|
---
|
||||||
Mount a folder from the *remote* side via SSHFS.
|
|
||||||
|
|
||||||
```bash
|
## 🚀 Why BackTunnel?
|
||||||
backtunnel-access /path/to/folder from remoteuser:remotehost [options]
|
|
||||||
# or: remoteuser@remotehost
|
|
||||||
```
|
|
||||||
|
|
||||||
**Options**
|
* **Works behind NAT/firewalls**: reverse SSH tunnels, no port forwarding needed.
|
||||||
- `-p, --port <PORT>`: Port on the remote host where the reverse tunnel listens (default: 2222)
|
* **Private by design**: no third-party relays or cloud.
|
||||||
- `-m, --mount-point <PATH>`: Local mount point (default: `~/remote-rssh`)
|
* **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.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📁 Profiles (named remotes)
|
## ✨ Commands
|
||||||
|
|
||||||
BackTunnel supports **profiles** to simplify connections. Instead of typing
|
### `backtunnel-share` — start a share
|
||||||
`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)
|
*(sharing side)*
|
||||||
|
|
||||||
System-wide default: /etc/backtunnel/profiles.ini (admins can edit)
|
```bash
|
||||||
Packaged example: /usr/share/backtunnel/profiles.ini
|
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
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔒 Temporary, tunnel-only access (restricted key)
|
### `backtunnel-access` — mount a share
|
||||||
|
|
||||||
By default, if you install a normal SSH key on the sharing machine, that key could also be used for direct SSH (if the server is reachable). To keep access **strictly temporary** and **usable only through the reverse tunnel**, use a **restricted key** in `authorized_keys`.
|
*(accessing side)*
|
||||||
|
|
||||||
This approach:
|
|
||||||
- **Allows SFTP/sshfs only** (no shell).
|
|
||||||
- **Only works via the reverse tunnel** (server sees the client as `127.0.0.1`).
|
|
||||||
- **Stops working** automatically when the reverse tunnel (started by `backtunnel-share`) ends.
|
|
||||||
|
|
||||||
### 1) Create a dedicated key on the client (access side)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_backtunnel -C backtunnel
|
backtunnel-access /path/to/folder from user@remotehost [options]
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2) Copy the public key to the server via the tunnel once
|
**Options:**
|
||||||
|
|
||||||
You’ll be prompted for the server password this one time, while the tunnel is up.
|
* `-p, --port <PORT>` — Remote tunnel port (default: `2222`)
|
||||||
|
* `-m, --mount-point <PATH>` — Local mount point (default: `~/remote-rssh`)
|
||||||
|
|
||||||
|
Unmount with:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ssh-copy-id -p 2222 -i ~/.ssh/id_ed25519_backtunnel.pub user@localhost
|
fusermount -u ~/remote-rssh
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3) Restrict that key in authorized_keys on the server
|
---
|
||||||
|
|
||||||
Edit the newly added line for this key in ~/.ssh/authorized_keys on the server and prefix it with:
|
## 📁 Profiles
|
||||||
|
|
||||||
|
Simplify frequent shares with `~/.config/backtunnel/profiles.ini`.
|
||||||
|
Example:
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
from="127.0.0.1",command="internal-sftp",restrict
|
[default]
|
||||||
|
tunnel_port=4422
|
||||||
|
invite_mount=$HOME/shared
|
||||||
|
|
||||||
|
[work]
|
||||||
|
user=alice
|
||||||
|
host=vps.example.com
|
||||||
|
tunnel_port=4423
|
||||||
```
|
```
|
||||||
|
|
||||||
The final line should look like:
|
Use with:
|
||||||
|
|
||||||
```ini
|
|
||||||
from="127.0.0.1",command="internal-sftp",restrict ssh-ed25519 AAAAC3... backtunnel
|
|
||||||
```
|
|
||||||
|
|
||||||
- from="127.0.0.1" limits use to connections that arrive via the reverse tunnel.
|
|
||||||
- command="internal-sftp" forces SFTP only (sshfs uses SFTP).
|
|
||||||
- restrict implies no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding.
|
|
||||||
|
|
||||||
💡 One-liner (no editor): prepend restrictions while appending your key
|
|
||||||
```bash
|
|
||||||
( printf 'from="127.0.0.1",command="internal-sftp",restrict '; cat ~/.ssh/id_ed25519_backtunnel.pub ) \
|
|
||||||
| ssh -p 2222 user@localhost 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4) Use as normal with BackTunnel
|
|
||||||
|
|
||||||
Start the share on the server:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
backtunnel-share /path/to/folder with user@REMOTE for 2h
|
backtunnel-share ~/reports with @work for 6h -i
|
||||||
```
|
|
||||||
|
|
||||||
Mount on the client (no password prompts now):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p ~/remote-rssh
|
|
||||||
backtunnel-access /path/to/folder from user@REMOTE -p 2222 -m ~/remote-rssh
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5) Cleanup (optional)
|
|
||||||
|
|
||||||
After you’re done, remove the restricted key line from ~/.ssh/authorized_keys on the server (or keep it for next time—it's safe: it only works via the tunnel, and only for SFTP).
|
|
||||||
|
|
||||||
> If you keep it, the key does not grant shell access and cannot be used over the network directly thanks to from="127.0.0.1".
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Troubleshooting
|
|
||||||
|
|
||||||
- If sftp -P 2222 user@localhost or sshfs still asks for a password:
|
|
||||||
|
|
||||||
- The restricted key line may be malformed (missing comma or options).
|
|
||||||
- File permissions: ~/.ssh should be 700, authorized_keys should be 600 on the server.
|
|
||||||
- Too many keys tried: you can force the key with:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
ssh -i ~/.ssh/id_ed25519_backtunnel -p 2222 user@localhost true
|
|
||||||
```
|
|
||||||
|
|
||||||
- If your mount point is ~-based, don’t quote it (~/remote-rssh is OK; '~/remote-rssh' won’t expand).
|
|
||||||
|
|
||||||
If you’d also like a brief “restricted key” note in the man page later, say the word and I’ll hand you a ready-to-paste `.1` section too.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 🖥️ 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`).
|
|
||||||
|
|
||||||
### Terminal launch from Dolphin (no dialogs)
|
|
||||||
If you prefer a terminal workflow, Dolphin’s service menus can launch BackTunnel in your **preferred terminal**. We ship a small opener `backtunnel-open-term` that picks Konsole, Kitty, Alacritty, GNOME Console, Tilix, Xfce Terminal, or xterm (whichever is available).
|
|
||||||
|
|
||||||
- **Share via BackTunnel…** → `backtunnel-open-term backtunnel-share-tui %f`
|
|
||||||
- **Access via BackTunnel…** → `backtunnel-open-term backtunnel-access-tui %f`
|
|
||||||
|
|
||||||
Each run produces a log under `${XDG_STATE_HOME:-$HOME/.local/state}/backtunnel/servicemenu.*.log` (latest 10 kept). Set `BACKTUNNEL_DEBUG=1` for extra shell tracing in the launched scripts.
|
|
||||||
|
|
||||||
|
|
||||||
### 🖱️ 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 `~/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 "$HOME/remote-rssh"
|
|
||||||
# Unmount when done:
|
|
||||||
fusermount -u ~/remote-rssh # or: umount ~/remote-rssh
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔐 Requirements
|
## 🔒 Security
|
||||||
- `ssh`, `sshfs`, `timeout`, `konsole`, `kdialog`
|
|
||||||
- Optional:
|
* **Restricted keys**: usable only through the tunnel (127.0.0.1).
|
||||||
- `bash-completion`
|
* **SFTP-only**: enforced with `internal-sftp,restrict`.
|
||||||
- `qrencode` (for QR-code invites)
|
* **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
|
## 📦 Install
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo bash scripts/install.sh
|
sudo bash scripts/install.sh
|
||||||
|
make init # copy example profiles.ini
|
||||||
```
|
```
|
||||||
|
|
||||||
Uninstall:
|
Uninstall:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo bash scripts/uninstall.sh
|
sudo bash scripts/uninstall.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Arch Linux:
|
||||||
|
|
||||||
## 📦 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
|
```bash
|
||||||
git tag -a v1.2.0 -m "BackTunnel 1.2.0"
|
makepkg -si
|
||||||
git push --tags
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 📖 Man Page
|
## 📖 Man Page
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
man backtunnel
|
man backtunnel
|
||||||
```
|
```
|
||||||
@@ -235,4 +170,39 @@ man backtunnel
|
|||||||
---
|
---
|
||||||
|
|
||||||
## 🧾 License
|
## 🧾 License
|
||||||
Licensed under **GNU GPL v3.0**. See `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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user