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: ~/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 "$HOME/remote-rssh"

Unmount on the remote side with:

fusermount -u ~/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: ~/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

---

🔒 Temporary, tunnel-only access (restricted key)

By default, if you install a normal SSH key on the sharing machine, that key could also be used for direct SSH (if the server is reachable). To keep access strictly temporary and usable only through the reverse tunnel, use a restricted key in authorized_keys.

This approach:

• Allows SFTP/sshfs only (no shell).
• Only works via the reverse tunnel (server sees the client as 127.0.0.1).
• Stops working automatically when the reverse tunnel (started by backtunnel-share) ends.

1) Create a dedicated key on the client (access side)

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_backtunnel -C backtunnel

2) Copy the public key to the server via the tunnel once

You’ll be prompted for the server password this one time, while the tunnel is up.

ssh-copy-id -p 2222 -i ~/.ssh/id_ed25519_backtunnel.pub user@localhost

3) Restrict that key in authorized_keys on the server

Edit the newly added line for this key in ~/.ssh/authorized_keys on the server and prefix it with:

from="127.0.0.1",command="internal-sftp",restrict

The final line should look like:

from="127.0.0.1",command="internal-sftp",restrict ssh-ed25519 AAAAC3... backtunnel

• from="127.0.0.1" limits use to connections that arrive via the reverse tunnel.
• command="internal-sftp" forces SFTP only (sshfs uses SFTP).
• restrict implies no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding.

💡 One-liner (no editor): prepend restrictions while appending your key

( printf 'from="127.0.0.1",command="internal-sftp",restrict '; cat ~/.ssh/id_ed25519_backtunnel.pub ) \
| ssh -p 2222 user@localhost 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'

4) Use as normal with BackTunnel

Start the share on the server:

backtunnel-share /path/to/folder with user@REMOTE for 2h

Mount on the client (no password prompts now):

mkdir -p ~/remote-rssh
backtunnel-access /path/to/folder from user@REMOTE -p 2222 -m ~/remote-rssh

5) Cleanup (optional)

After you’re done, remove the restricted key line from ~/.ssh/authorized_keys on the server (or keep it for next time—it's safe: it only works via the tunnel, and only for SFTP).

If you keep it, the key does not grant shell access and cannot be used over the network directly thanks to from="127.0.0.1".

---

Troubleshooting

• If sftp -P 2222 user@localhost or sshfs still asks for a password:

  • The restricted key line may be malformed (missing comma or options).
  • File permissions: ~/.ssh should be 700, authorized_keys should be 600 on the server.
  • Too many keys tried: you can force the key with:

ssh -i ~/.ssh/id_ed25519_backtunnel -p 2222 user@localhost true

• If your mount point is -based, don’t quote it (/remote-rssh is OK; '~/remote-rssh' won’t expand).

If you’d also like a brief “restricted key” note in the man page later, say the word and I’ll hand you a ready-to-paste .1 section too.

---

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

Terminal launch from Dolphin (no dialogs)

If you prefer a terminal workflow, Dolphin’s service menus can launch BackTunnel in your preferred terminal. We ship a small opener backtunnel-open-term that picks Konsole, Kitty, Alacritty, GNOME Console, Tilix, Xfce Terminal, or xterm (whichever is available).

• Share via BackTunnel… → backtunnel-open-term backtunnel-share-tui %f
• Access via BackTunnel… → backtunnel-open-term backtunnel-access-tui %f

Each run produces a log under ${XDG_STATE_HOME:-$HOME/.local/state}/backtunnel/servicemenu.*.log (latest 10 kept). Set BACKTUNNEL_DEBUG=1 for extra shell tracing in the launched scripts.

🖱️ 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 ~/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 "$HOME/remote-rssh"
# Unmount when done:
fusermount -u ~/remote-rssh    # or: umount ~/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.