323 lines
8.9 KiB
Markdown
323 lines
8.9 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č
|