PMISuite/BackTunnel
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add backtunnel-umount script, host key policy support, and extend TUI/CLI integration

Browse Source 
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.
This commit is contained in:
Matjaž Mozetič
2025-09-21 18:56:15 +02:00
parent 0e82955af5
commit ae8ab9a7e0
9 changed files with 344 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
README.md
View File

@@ -8,24 +8,31 @@ No third-party relay, no cloud dependency – just peer-to-peer, temporary, SSH-
## ⚡ 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
fusermount -u ~/remote-rssh
backtunnel-umount ~/remote-rssh
```
---
@@ -35,81 +42,230 @@ fusermount -u ~/remote-rssh
- **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 tunnel and are auto-removed when the share ends.
- **Profiles**: save defaults and common remotes in `profiles.ini`.
- **Desktop integration**: Dolphin (KDE) service menus for GUI sharing and access.
- **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
### Sharing
```bash
backtunnel-share /path/to/folder with user@host for <duration> [options]
```
- `-p, --tunnel-port` Remote bind port (default: 2222)
- `-l, --local-ssh-port` Local sshd port to expose (default: 22)
- `-i, --invite` Print invite line
- `--qr` Show QR code (requires qrencode)
- `--allow-key FILE` Authorize a provided public key
- `--allow-known NAME` Authorize a stored key (~/.config/backtunnel/authorized/NAME.pub)
### Sharer side
### Accessing
```bash
backtunnel-access /path/to/folder from user@host [options]
```
- `-p, --port` Tunnel port (default: 2222)
- `-m, --mount-point` Local mount point (default: ~/remote-rssh)
- 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.
---
## 📁 Profiles
## 🔒 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:
`~/.config/backtunnel/profiles.ini`:
```ini
[default]
tunnel_port=2222
invite=true
local_ssh_port=22
invite_mount=$HOME/remote-rssh
invite=true
qr=false
[work]
user=alice
host=vps.example.com
tunnel_port=4422
```
Usage:
```bash
backtunnel-share ~/reports with @work for 6h -i --allow-known alice
```
- Usage with @profile:
```bash
backtunnel-share ~/reports with @work for 6h -i --allow-known alice
```
---
## 🖥️ Dolphin Integration
## 🧭 Bash Completion
- **Share via BackTunnel…** – GUI dialog for sharer options.
- **Access via BackTunnel…** – GUI dialog for accessor options.
Logs are written to:
```
~/.local/state/backtunnel/servicemenu.*.log
```
- 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).
---
## 📦 Install
## 🖥️ 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
@@ -118,8 +274,44 @@ sudo PURGE=1 bash scripts/uninstall.sh
---
## 📖 Documentation
## 🔍 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
```