diff --git a/README.md b/README.md index 23185f5..0a3ce01 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,32 @@ backtunnel-share /path/to/folder with remoteuser:remotehost for [opti **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: `/mnt/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`) + +**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. @@ -30,6 +56,8 @@ backtunnel-access /path/to/folder from remoteuser:remotehost [options] - `-p, --port `: Port on the remote host where the reverse tunnel listens (default: 2222) - `-m, --mount-point `: Local mount point (default: `/mnt/remote-rssh`) +--- + ## 🧰 Dolphin Service Menus Two context actions for Dolphin: @@ -40,9 +68,15 @@ Installed into: - Plasma 6: `/usr/share/kio/servicemenus/` - Plasma 5: `/usr/share/kservices5/ServiceMenus/` +--- + ## 🔐 Requirements - `ssh`, `sshfs`, `timeout`, `konsole`, `kdialog` -- Optional: `bash-completion` +- Optional: + - `bash-completion` + - `qrencode` (for QR-code invites) + +--- ## 📦 Install ```bash @@ -53,10 +87,14 @@ Uninstall: sudo bash scripts/uninstall.sh ``` +--- + ## 📖 Man Page ```bash man backtunnel ``` +--- + ## 🧾 License Licensed under **GNU GPL v3.0**. See `LICENSE`. diff --git a/man/backtunnel.1 b/man/backtunnel.1 index 10576d6..989119d 100644 --- a/man/backtunnel.1 +++ b/man/backtunnel.1 @@ -1,4 +1,4 @@ -.TH backtunnel 1 "September 2025" "1.1" "BackTunnel – Reverse SSH Sharing Toolkit" +.TH backtunnel 1 "September 2025" "1.2" "BackTunnel – Reverse SSH Sharing Toolkit" .SH NAME backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and access @@ -15,6 +15,9 @@ backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and acc The tunnel exposes the local sshd (typically port 22) on a loopback port on the remote host using \fBssh -R\fR. The sharing ends automatically after the given \fIduration\fR via \fBtimeout\fR. +With the \fB--invite\fR option, \fBbacktunnel-share\fR prints a ready-to-copy access command for the remote user, +which can be pasted directly into a chat or terminal. The invite can also be rendered as a QR code or written to a file. + \fBbacktunnel-access\fR mounts the shared folder from the remote side using \fBsshfs\fR by connecting to \fBlocalhost:\fR on the remote host (the port exposed by \fBbacktunnel-share\fR). .SH OPTIONS @@ -27,6 +30,22 @@ Remote port to bind with \fB-R\fR (default: 2222). .B -l, --local-ssh-port Local sshd port to forward to (default: 22). +.TP +.B -i, --invite +Print a ready-to-copy invite command for the remote user. + +.TP +.B --invite-mount +Mount point suggested in the invite (default: /mnt/remote-rssh). + +.TP +.B --invite-file +Also write the invite text (including unmount hint) to the given file. + +.TP +.B --qr +Render the invite as a terminal QR code (requires \fBqrencode\fR). + .SS backtunnel-access options .TP .B -p, --port @@ -60,6 +79,16 @@ Share for 1 day, using custom ports: .B backtunnel-share /home/user/docs with alice:vps.example.com for 1d -p 4422 -l 2222 +.TP +Share with invite printed: +.B backtunnel-share +/home/user/docs with alice@vps.example.com for 2h -i + +.TP +Share with QR invite: +.B backtunnel-share +/home/user/docs with alice@vps.example.com for 2h -i --qr + .TP Mount with default port and mount point: .B backtunnel-access @@ -74,8 +103,11 @@ Mount with custom port and mount point: By default, \fBssh -R\fR binds to 127.0.0.1 on the remote side, limiting access to local users on the remote machine. The client connects to \fBlocalhost:\fR from the remote host. +The invite feature is intended for convenience: copy-paste the printed command into chat for the remote user. +Unmount with \fBfusermount -u \fR after use. + .SH SEE ALSO -ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1) +ssh(1), sshfs(1), timeout(1), autossh(1), qrencode(1), fusermount(1) .SH AUTHOR Matjaž Mozetič diff --git a/scripts/backtunnel-share b/scripts/backtunnel-share index 7617554..6aada9a 100644 --- a/scripts/backtunnel-share +++ b/scripts/backtunnel-share @@ -4,7 +4,7 @@ # backtunnel-share: Share a folder using reverse SSH for a limited duration # Syntax: backtunnel-share /path/to/folder with remoteuser:remotehost for 2h -# Options: -p|--tunnel-port -l|--local-ssh-port -h|--help +# Options: -p|--tunnel-port -l|--local-ssh-port -i|--invite [--invite-mount ] [--invite-file ] [--qr] -h|--help set -euo pipefail @@ -12,6 +12,11 @@ TUNNEL_PORT=2222 # remote-side port exposed via -R LOCAL_SSH_PORT=22 # local sshd port to forward to DURATION="" # required: e.g. 30m, 2h, 1d +INVITE=false # print a ready-to-copy access command +INVITE_MOUNT="/mnt/remote-rssh" +INVITE_FILE="" +QR=false # render invite as terminal QR (requires qrencode) + usage() { cat >&2 < "${INVITE_FILE}" + echo "Saved invite to: ${INVITE_FILE}" + fi + if $QR; then + if command -v qrencode >/dev/null 2>&1; then + echo + echo "📱 QR (scan to copy the command):" + printf "%s" "${INVITE_CMD}" | qrencode -t ansiutf8 + else + echo "⚠️ 'qrencode' not installed; skipping QR." + fi + fi + echo +fi + echo "Tip: On the remote side, mount with:" echo " backtunnel-access '${FOLDER}' from ${REMOTE_USER}@${REMOTE_HOST} -p ${TUNNEL_PORT}"