BackTunnel/README.md

BackTunnel – Reverse SSH Folder Sharing Toolkit

Share and mount folders between Linux machines behind NAT/firewalls using two friendly commands.

✨ Commands

backtunnel-share

Start a reverse SSH tunnel from the sharing machine for a limited time.

backtunnel-share /path/to/folder with remoteuser:remotehost for <duration> [options]
# or: remoteuser@remotehost

Duration formats: 30m, 2h, 1d (passed to timeout)

Options

• -p, --tunnel-port <PORT>: Remote port to expose with -R (default: 2222)
• -l, --local-ssh-port <PORT>: Local sshd port to forward to (default: 22)
• -i, --invite: Print a ready-to-copy access command for the remote user
• --invite-mount <PATH>: Suggest mount point in the invite (default: /mnt/remote-rssh)
• --invite-file <FILE>: Also write the invite text (including unmount hint) to a file
• --qr: Render the invite as a QR code (requires qrencode)

Examples

# 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:

backtunnel-access '/home/user/projects' from alice@vps.example.com -p 4422 -m '/mnt/remote-rssh'

Unmount on the remote side with:

fusermount -u /mnt/remote-rssh

backtunnel-access

Mount a folder from the remote side via SSHFS.

backtunnel-access /path/to/folder from remoteuser:remotehost [options]
# or: remoteuser@remotehost

Options

• -p, --port <PORT>: Port on the remote host where the reverse tunnel listens (default: 2222)
• -m, --mount-point <PATH>: Local mount point (default: /mnt/remote-rssh)

---

📁 Profiles (named remotes)

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:

📖 Example config: see docs/profiles.ini.example

System-wide default: /etc/backtunnel/profiles.ini (admins can edit) Packaged example: /usr/share/backtunnel/profiles.ini

---

🖥️ 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).

🖱️ 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 /mnt/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):

# Paste the invite you sent them, e.g.:
backtunnel-access '/path/to/folder' from user@vps.example.com -p 2222 -m '/mnt/remote-rssh'
# Unmount when done:
fusermount -u /mnt/remote-rssh    # or: umount /mnt/remote-rssh

---

🔐 Requirements

• ssh, sshfs, timeout, konsole, kdialog
• Optional:
  • bash-completion
  • qrencode (for QR-code invites)

---

📦 Install

sudo bash scripts/install.sh

Uninstall:

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:

   git tag -a v1.2.0 -m "BackTunnel 1.2.0"
   git push --tags

📖 Man Page

man backtunnel

---

🧾 License

Licensed under GNU GPL v3.0. See LICENSE.