sysadminmatmoz
ae8ab9a7e0
Introduce `backtunnel-umount` as a portable unmount helper, preferring `fusermount3`, `fusermount`, or `umount`. Add `BACKTUNNEL_HOSTKEY_POLICY` for configurable host key handling in `backtunnel-share` and `backtunnel-access`. Update TUIs for remote folder prompts and mount point handling. Enhance bash completion for TUI commands with directory suggestions. Revamp terminal selection logic in `backtunnel-open-term` to prioritize modern emulators like wezterm. Extend tests with scaffolds for host key policy and unmount behavior. Update README with new scripts, workflows, features, and troubleshooting tips.
323 lines
9.0 KiB
Markdown
323 lines
9.0 KiB
Markdown
# BackTunnel – Secure Reverse SSH Folder Sharing Toolkit
|
||
|
||
**BackTunnel** is a lightweight toolkit to share and mount folders between Linux machines behind NAT or firewalls using **reverse SSH tunnels**.
|
||
No third-party relay, no cloud dependency – just peer-to-peer, temporary, SSH-based access.
|
||
|
||
---
|
||
|
||
## ⚡ Quick Start
|
||
|
||
### 1. Accessor: Prepare your key (one-time)
|
||
|
||
```bash
|
||
backtunnel-keys print
|
||
```
|
||
|
||
Send the printed public key to the sharer.
|
||
|
||
### 2. Sharer: Start sharing and authorize the accessor
|
||
|
||
```bash
|
||
backtunnel-share ~/Documents with alice@remotehost for 2h -i --allow-key ./alice.pub
|
||
```
|
||
|
||
This injects a **temporary, restricted SFTP-only key** and prints an invite.
|
||
|
||
### 3. Accessor: Mount the shared folder
|
||
|
||
```bash
|
||
backtunnel-access '/home/sharer/Documents' from alice@remotehost -p 2222 -m ~/remote-rssh
|
||
```
|
||
|
||
Unmount with:
|
||
|
||
```bash
|
||
backtunnel-umount ~/remote-rssh
|
||
```
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- **NAT/firewall friendly**: works without port forwarding.
|
||
- **Temporary by design**: shares auto-expire after a set duration.
|
||
- **Invite workflow**: sharer sends a one-liner or QR code to accessor.
|
||
- **Restricted keys**: accessor keys are usable only for SFTP via the reverse tunnel and can be auto-added for the session.
|
||
- **Profiles**: save defaults and common remotes in profiles.ini.
|
||
- **Host key policy**: configurable StrictHostKeyChecking via BACKTUNNEL_HOSTKEY_POLICY.
|
||
- **Desktop integration**: Dolphin (KDE) service menus for GUI/TUI sharing and access.
|
||
- **Convenient TUIs/GUI**: guided prompts for sharer/accessor; terminal opener detects installed terminals.
|
||
- **Bash completion**: contextual completion for both CLI commands and TUIs.
|
||
- **Logs with rotation**: servicemenu invocations write logs and keep the last 10 entries.
|
||
|
||
---
|
||
|
||
## 🧠 Roles and Flow
|
||
|
||
- Sharer: exposes a local SSH service back to a remote host for a limited time. Runs backtunnel-share.
|
||
- Accessor: connects to the sharer via the remote host’s `127.0.0.1:PORT` and mounts a folder with sshfs. Runs backtunnel-access.
|
||
- Reverse tunnel: the sharer’s ssh -R binds `127.0.0.1:PORT` on the remote host and forwards back to the sharer’s sshd.
|
||
|
||
---
|
||
|
||
## ✅ Requirements
|
||
|
||
- Linux with Bash
|
||
- OpenSSH client (ssh, sftp)
|
||
- sshfs (FUSE) on the accessor machine
|
||
- Optional:
|
||
- qrencode (for QR code invites)
|
||
- A terminal emulator for service menu helpers (e.g., konsole, gnome-terminal, wezterm, kitty, etc.)
|
||
|
||
---
|
||
|
||
## 🔑 Commands
|
||
|
||
### Sharer side
|
||
|
||
- backtunnel-share
|
||
- Start a time-bounded reverse SSH tunnel and optionally print an invite.
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-share /path/to/folder with user@host for <duration> [options]
|
||
```
|
||
- Duration: 10m, 30m, 1h, 2h, 6h, 12h, 1d, 2d (single unit e.g., 30m, 2h, 1d)
|
||
- Options:
|
||
- -p, --tunnel-port N: Remote bind port (default: 2222)
|
||
- -l, --local-ssh-port N: Local sshd port to forward to (default: 22)
|
||
- -i, --invite: Print a one-liner invite for the accessor
|
||
- --invite-mount PATH: Suggested mount point in the invite (default: $HOME/remote-rssh)
|
||
- --invite-file FILE: Save the invite text (with unmount hint) to a file
|
||
- --qr: Also show a QR code for the invite (requires qrencode)
|
||
- --allow-key FILE: Temporarily authorize an accessor public key for this session
|
||
- --allow-known NAME: Authorize a stored key (~/.config/backtunnel/authorized/NAME.pub)
|
||
- -h, --help: Show usage
|
||
|
||
- backtunnel-share-tui
|
||
- Minimal TUI wrapper prompting for remote, duration, ports, and invite options, then runs backtunnel-share.
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-share-tui <folder>
|
||
```
|
||
|
||
- backtunnel-authorize
|
||
- Store a named accessor public key for --allow-known usage.
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-authorize <name> <pubkey-file>
|
||
```
|
||
- Stores at: `${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/authorized/<name>.pub`
|
||
|
||
### Accessor side
|
||
|
||
- backtunnel-access
|
||
- Mount a folder over SFTP via the reverse tunnel’s `127.0.0.1:PORT`.
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-access /remote/folder from user@host [-p PORT] [-m MOUNTPOINT]
|
||
```
|
||
- Options:
|
||
- -p, --port N: Tunnel port on the remote host (default: 2222)
|
||
- -m, --mount-point PATH: Local mount point (default: $HOME/remote-rssh)
|
||
- -h, --help: Show usage
|
||
- Behavior:
|
||
- Checks mount point readiness and warns if not empty.
|
||
- Tries passwordless auth via a dedicated identity if present (~/.ssh/id_ed25519_backtunnel).
|
||
- Performs a quick SFTP visibility check of the target folder.
|
||
- Mounts with reconnect/keepalives.
|
||
|
||
- backtunnel-access-tui
|
||
- Minimal TUI wrapper prompting for remote, tunnel port, remote folder, and mount point.
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-access-tui <selected-dir>
|
||
```
|
||
|
||
- backtunnel-keys
|
||
- Manage the accessor-side dedicated key pair (~/.ssh/id_ed25519_backtunnel).
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-keys print # emit public key (generate if missing)
|
||
backtunnel-keys path # show key paths
|
||
```
|
||
|
||
- backtunnel-auth-setup
|
||
- Initialize a tunnel-only, SFTP-only authorized_keys entry on the remote (via the tunnel).
|
||
- Syntax:
|
||
```bash
|
||
backtunnel-auth-setup [-p PORT] user@localhost
|
||
```
|
||
- Installs a restricted entry:
|
||
from="127.0.0.1",command="internal-sftp",restrict <pubkey>
|
||
|
||
- backtunnel-umount
|
||
- Portable unmount helper (prefers fusermount3, then fusermount, then umount).
|
||
- Syntax:
|
||
|
||
```bash
|
||
backtunnel-umount <mountpoint>
|
||
```
|
||
|
||
- backtunnel-open-term
|
||
- Launch a command in an available terminal emulator; logs output with simple rotation.
|
||
- Automatically detects terminals (prefers konsole on KDE; supports wezterm, kitty, alacritty, gnome-terminal, kgx, tilix, xfce4-terminal, xterm).
|
||
- Used by service menus/GUI wrappers.
|
||
|
||
---
|
||
|
||
## 🔒 Security Model
|
||
|
||
- Reverse tunnel bind: remote side binds on `127.0.0.1:PORT` (loopback only).
|
||
- Access is SFTP-based:
|
||
- Invite flow can be paired with a restricted authorized_keys entry:
|
||
- from="127.0.0.1",command="internal-sftp",restrict
|
||
- This limits usage to SFTP over the reverse tunnel only; no shell or port forwarding.
|
||
- Temporary authorization:
|
||
- Sharer can temporarily add an accessor public key for the session; it’s removed on exit.
|
||
- Host key policy:
|
||
- Controlled via the environment variable BACKTUNNEL_HOSTKEY_POLICY with values:
|
||
- accept-new (default), yes, no, ask
|
||
- Applied to ssh, sftp, and the ssh command used by sshfs.
|
||
|
||
---
|
||
|
||
## 🧩 Profiles
|
||
|
||
- Config locations (higher precedence first):
|
||
- `${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/profiles.ini`
|
||
- /etc/backtunnel/profiles.ini
|
||
- /usr/share/backtunnel/profiles.ini
|
||
- Example:
|
||
|
||
```ini
|
||
[default]
|
||
tunnel_port=2222
|
||
local_ssh_port=22
|
||
invite_mount=$HOME/remote-rssh
|
||
invite=true
|
||
qr=false
|
||
|
||
[work]
|
||
user=alice
|
||
host=vps.example.com
|
||
tunnel_port=4422
|
||
```
|
||
|
||
- Usage with @profile:
|
||
```bash
|
||
backtunnel-share ~/reports with @work for 6h -i --allow-known alice
|
||
```
|
||
|
||
---
|
||
|
||
## 🧭 Bash Completion
|
||
|
||
- Source completions/backtunnel.bash or install it via your system’s completion.d directory.
|
||
- Provides:
|
||
- Keyword scaffolding (with/from/for)
|
||
- @profile expansion
|
||
- Suggestions for durations and ports
|
||
- Key name/file completion for --allow-known/--allow-key
|
||
- Path completion for the first positional and mount path options
|
||
- Includes minimal completion for TUIs (first positional directory).
|
||
|
||
---
|
||
|
||
## 🖥️ Desktop Integration (KDE Dolphin)
|
||
|
||
- Right-click in a folder:
|
||
- “Share via BackTunnel…” → opens a GUI/TUI flow for the sharer.
|
||
- “Access via BackTunnel (mount here)…” → opens a GUI/TUI flow for the accessor.
|
||
- Logs:
|
||
```
|
||
~/.local/state/backtunnel/servicemenu.*.log
|
||
```
|
||
The launcher keeps the last 10 logs (simple rotation).
|
||
|
||
---
|
||
|
||
## 🌐 Environment Variables
|
||
|
||
- BACKTUNNEL_HOSTKEY_POLICY
|
||
- Controls StrictHostKeyChecking for ssh/sftp/sshfs:
|
||
- Values: accept-new (default), yes, no, ask
|
||
- Example:
|
||
```bash
|
||
BACKTUNNEL_HOSTKEY_POLICY=strict # alias for 'yes' in many contexts
|
||
BACKTUNNEL_HOSTKEY_POLICY=accept-new
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ Installation
|
||
|
||
### From source
|
||
|
||
```bash
|
||
sudo bash scripts/install.sh
|
||
make init # copy example profiles.ini
|
||
```
|
||
|
||
### Arch Linux
|
||
|
||
```bash
|
||
makepkg -si
|
||
```
|
||
|
||
Uninstall:
|
||
|
||
```bash
|
||
sudo bash scripts/uninstall.sh
|
||
# or with purge of defaults
|
||
sudo PURGE=1 bash scripts/uninstall.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 Troubleshooting
|
||
|
||
- Port already in use on remote:
|
||
- backtunnel-share warns if `127.0.0.1:PORT` is busy; choose another with -p.
|
||
- Missing sshfs:
|
||
- Install sshfs on the accessor machine; ensure FUSE is available.
|
||
- SFTP path is not listable:
|
||
- backtunnel-access warns if SFTP cannot list the path. Verify folder existence and permissions.
|
||
- Passwordless auth isn't set:
|
||
- Try:
|
||
```bash
|
||
backtunnel-auth-setup -p <PORT> <user>@localhost
|
||
```
|
||
- Unmount fails:
|
||
- Use the portable helper:
|
||
```bash
|
||
backtunnel-umount <mountpoint>
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Testing
|
||
|
||
- Bats scaffolds are provided to extend:
|
||
- tests/test-umount.bats
|
||
- tests/test-hostkey-policy.bats
|
||
|
||
Run tests (example):
|
||
|
||
```bash
|
||
bats tests
|
||
```
|
||
|
||
---
|
||
|
||
## 📖 Man Page
|
||
|
||
```bash
|
||
man backtunnel
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 License
|
||
GNU GPL v3.0
|
||
© 2025 LUXIM d.o.o., Slovenia – Matjaž Mozetič
|