From cb81c1671b0ca1e7f98c8cec0ecace7c7ec43e13 Mon Sep 17 00:00:00 2001 From: sysadminmatmoz Date: Sat, 20 Sep 2025 10:58:02 +0200 Subject: [PATCH] Revamp README for enhanced clarity and usability: streamline commands, add quick start, highlight key features, improve examples, and restructure sections for better organization. --- README.md | 304 ++++++++++++++++++++++++------------------------------ 1 file changed, 137 insertions(+), 167 deletions(-) diff --git a/README.md b/README.md index 3365d9e..e672286 100644 --- a/README.md +++ b/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` -Start a reverse SSH tunnel from the *sharing* machine for a limited time. +## ⚡ Quick Start (3 steps) -```bash -backtunnel-share /path/to/folder with remoteuser:remotehost for [options] -# or: remoteuser@remotehost -``` +1. **On the sharing machine (server):** -**Duration formats:** `30m`, `2h`, `1d` (passed to `timeout`) + ```bash + backtunnel-share ~/Documents with user@remotehost for 2h -i + ``` -**Options** -- `-p, --tunnel-port `: Remote port to expose with `-R` (default: 2222) -- `-l, --local-ssh-port `: Local sshd port to forward to (default: 22) -- `-i, --invite`: Print a ready-to-copy access command for the remote user -- `--invite-mount `: Suggest mount point in the invite (default: `~/remote-rssh`) -- `--invite-file `: Also write the invite text (including unmount hint) to a file -- `--qr`: Render the invite as a QR code (requires `qrencode`) + → Opens a tunnel for 2 hours and prints an **invite**. -**Examples** -```bash -# Share for 2h -backtunnel-share ~/projects with alice@vps.example.com for 2h +2. **Send the invite** (via chat, email, QR). It looks like: -# Share and print a one-liner invite for chat -backtunnel-share ~/projects with alice@vps.example.com for 2h -i + ```bash + backtunnel-auth-setup -p 2222 user@localhost + backtunnel-access '/home/alice/Documents' from user@remotehost -p 2222 -m "$HOME/remote-rssh" + ``` -# Share with custom ports and QR invite -backtunnel-share ~/projects with alice@vps.example.com for 1d -p 4422 -l 2222 -i --qr -``` +3. **On the accessing machine (client):** -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 "$HOME/remote-rssh" -``` + ```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: -Unmount on the remote side with: ```bash fusermount -u ~/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 -``` +## 🚀 Why BackTunnel? -**Options** -- `-p, --port `: Port on the remote host where the reverse tunnel listens (default: 2222) -- `-m, --mount-point `: Local mount point (default: `~/remote-rssh`) +* **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. --- -## 📁 Profiles (named remotes) +## ✨ Commands -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: +### `backtunnel-share` — start a share -📖 Example config: see [docs/profiles.ini.example](docs/profiles.ini.example) +*(sharing side)* -System-wide default: /etc/backtunnel/profiles.ini (admins can edit) -Packaged example: /usr/share/backtunnel/profiles.ini +```bash +backtunnel-share /path/to/folder with user@remotehost for [options] +``` + +**Duration formats:** `30m`, `2h`, `1d` +**Key options:** + +* `-p, --tunnel-port ` — Remote port (default: `2222`) +* `-l, --local-ssh-port ` — Local SSHD port (default: `22`) +* `-i, --invite` — Print a ready-to-copy **invite** +* `--invite-mount ` — 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`. - -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) +*(accessing side)* ```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 ` — Remote tunnel port (default: `2222`) +* `-m, --mount-point ` — Local mount point (default: `~/remote-rssh`) + +Unmount with: ```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 -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: - -```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: +Use with: ```bash -backtunnel-share /path/to/folder with user@REMOTE for 2h -``` - -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 +backtunnel-share ~/reports with @work for 6h -i ``` --- -## 🔐 Requirements -- `ssh`, `sshfs`, `timeout`, `konsole`, `kdialog` -- Optional: - - `bash-completion` - - `qrencode` (for QR-code invites) +## 🔒 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 ``` ---- - -## 📦 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**: +Arch Linux: ```bash - git tag -a v1.2.0 -m "BackTunnel 1.2.0" - git push --tags +makepkg -si ``` +--- + ## 📖 Man Page + ```bash man backtunnel ``` @@ -235,4 +170,39 @@ man backtunnel --- ## 🧾 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 +``` + +---