.TH backtunnel 1 "September 2025" "1.3" "BackTunnel – Reverse SSH Sharing Toolkit"

.SH NAME
backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and access (with profiles, temporary key authorization)

.SH SYNOPSIS
.B backtunnel-share
/path/to/folder with {remoteuser:remotehost|remoteuser@remotehost|@profilename} for <duration> [options]

.B backtunnel-access
/path/to/folder from {remoteuser:remotehost|remoteuser@remotehost} [options]

.SH DESCRIPTION
\fBbacktunnel-share\fR starts a reverse SSH tunnel from the local (sharing) machine to a remote,
reachable host. The tunnel exposes the local sshd (typically port 22) on a loopback port on the
remote host using \fBssh -R\fR. Sharing ends automatically after the given \fIduration\fR via \fBtimeout\fR.

\fBbacktunnel-access\fR mounts the shared folder from the remote side using \fBsshfs\fR by connecting
to \fBlocalhost:<port>\fR on the remote host (the port exposed by \fBbacktunnel-share\fR).

The tools support \fIprofiles\fR (named remotes and defaults) and a secure workflow without
password exchange using temporary, restricted keys.

.SH OPTIONS
.SS backtunnel-share options
.TP
.B -p, --tunnel-port <PORT>
Remote port to bind with \fB-R\fR (default: 2222).
.TP
.B -l, --local-ssh-port <PORT>
Local sshd port to forward to (default: 22).
.TP
.B -i, --invite
Print a ready-to-copy access command for the remote side. With \fB--allow-key\fR
or \fB--allow-known\fR, the invite includes only the mount command (no auth step).
.TP
.B --invite-mount <PATH>
Mount point suggested in invite (default: \fI$HOME/remote-rssh\fR).
.TP
.B --invite-file <FILE>
Also write the invite text (with unmount hint) to FILE.
.TP
.B --qr
Also print a QR code (requires \fBqrencode\fR).
.TP
.B --allow-key <FILE>
Temporarily authorize the accessor’s public key for the session by injecting a restricted
entry into \fI~/.ssh/authorized_keys\fR and removing it on exit. The line is prefixed with:
\fCfrom="127.0.0.1",command="internal-sftp",restrict\fR.
.TP
.B --allow-known <NAME>
Authorize a public key from \fI~/.config/backtunnel/authorized/NAME.pub\fR (same restrictions
and auto-removal as \fB--allow-key\fR).

.SS backtunnel-access options
.TP
.B -p, --port <PORT>
Remote port on which the reverse tunnel listens (default: 2222).
.TP
.B -m, --mount-point <PATH>
Local mount point for sshfs (default: \fI$HOME/remote-rssh\fR).

.SH PROFILES
Profiles allow you to use \fB@name\fR instead of \fIuser@host\fR and to set defaults.

The configuration search order is:
.TP
\fB~/.config/backtunnel/profiles.ini\fR
Per-user configuration file containing defaults and named profiles.
.TP
\fB/etc/backtunnel/profiles.ini\fR
System-wide default profiles (editable by admins).
.TP
\fB/usr/share/backtunnel/profiles.ini\fR
Packaged example/fallback used when user/system config is absent.

An example:
.PP
.nf
[default]
tunnel_port=2222
invite=true
invite_mount=$HOME/remote-rssh

[work]
user=alice
host=vps.example.com
tunnel_port=4422
.fi

Usage:
.PP
\fBbacktunnel-share ~/docs with @work for 6h -i --allow-known alice\fR

.SH SECURITY MODEL
The temporary authorized key is restricted with:
.PP
\fCfrom="127.0.0.1",command="internal-sftp",restrict\fR
.PP
This limits usage to the reverse tunnel (localhost on the remote end) and SFTP only (no shell,
no agent/X11/port forwarding). The entry is removed when the share ends or the process exits.

.SH EXAMPLES
.TP
Share for 2 hours on default ports:
\fBbacktunnel-share\fR /home/user/docs with alice@vps.example.com for 2h -i
.TP
Share for 1 day, using custom ports and a known key:
\fBbacktunnel-share\fR /home/user/docs with @work for 1d -p 4422 -l 2222 -i --allow-known alice
.TP
Mount with default port and mount point:
\fBbacktunnel-access\fR /home/user/docs from alice@vps.example.com
.TP
Mount with custom port and mount point:
\fBbacktunnel-access\fR /home/user/docs from alice@vps.example.com -p 4422 -m /mnt/alice-docs

.SH FILES
.TP
\fB~/.config/backtunnel/profiles.ini\fR
Per-user profiles and defaults.
.TP
\fB/etc/backtunnel/profiles.ini\fR
System-wide defaults.
.TP
\fB/usr/share/backtunnel/profiles.ini\fR
Packaged example.
.TP
\fB~/.config/backtunnel/authorized/*.pub\fR
Accessor public keys saved by \fBbacktunnel-authorize\fR for \fB--allow-known\fR.

.SH SEE ALSO
ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1),
\fBbacktunnel-keys\fR(1), \fBbacktunnel-auth-setup\fR(1)

.SH AUTHOR
Matjaž Mozetič