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

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

.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.
Profiles can be used to simplify the remote specification and default options.

\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).

.SH OPTIONS
.SS backtunnel-share options
.TP
.B -p, --tunnel-port <PORT>
Remote port to bind with \fB-R\fR (default: 2222). May be provided via profile.

.TP
.B -l, --local-ssh-port <PORT>
Local sshd port to forward to (default: 22). May be provided via profile.

.TP
.B -i, --invite
Print a ready-to-copy access command for the remote side.

.TP
.B --invite-mount <PATH>
Suggested mount point included in the invite text (default: /mnt/remote-rssh). May be provided via profile.

.TP
.B --invite-file <FILE>
Write the invite text (including unmount hint) to the given file.

.TP
.B --qr
Additionally render the invite as a QR code (requires \fBqrencode\fR).

.TP
.B -h, --help
Show usage.

.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: /mnt/remote-rssh).

.SH ARGUMENTS
.TP
.B /path/to/folder
Path to share (server) or to mount (client).

.TP
.B remoteuser:remotehost
Or \fBremoteuser@remotehost\fR. The remote host that accepts the initial SSH connection.

.TP
.B @profilename
A named profile that expands to \fBuser@host\fR and may also supply defaults for \fB--tunnel-port\fR,
\fB--local-ssh-port\fR, \fB--invite-mount\fR, and \fIduration\fR. See \fBPROFILES\fR.

.TP
.B <duration>
Time to keep the share active. Accepts \fBn\fR\fIs\fR|\fIm\fR|\fIh\fR|\fId\fR forms, e.g. 30m, 2h, 1d (passed to \fBtimeout\fR).
May be provided via the \fB[default]\fR profile; the positional \fI<duration>\fR takes precedence.

.SH PROFILES
BackTunnel can read defaults and named remote definitions from (searched in order):
.P
\fB~/.config/backtunnel/profiles.ini\fR (per-user)
.br
\fB/etc/backtunnel/profiles.ini\fR (system-wide default)
.br
\fB/usr/share/backtunnel/profiles.ini\fR (packaged example/fallback)
.P
Two kinds of sections are recognized:

.TP
.B [default]
Global defaults applied unless overridden by a named profile or CLI flags:
.IP
\fBduration\fR=2h
.br
\fBtunnel_port\fR=2222
.br
\fBlocal_ssh_port\fR=22
.br
\fBinvite_mount\fR=~/remote-rssh
.br
\fBinvite\fR=true|false
.br
\fBqr\fR=true|false

.TP
.B [name]
A named profile providing at least \fBuser\fR and \fBhost\fR, and optional overrides:
.IP
\fBuser\fR=alice
.br
\fBhost\fR=vps.example.com
.br
\fBtunnel_port\fR=4422
.br
\fBlocal_ssh_port\fR=22
.br
\fBinvite_mount\fR=/mnt/remote-rssh

.P
To use a profile, replace the remote with \fB@name\fR, e.g.:
.P
.nf
backtunnel-share /path/to/folder with @workvps for 1d
.fi
.P
Command-line options \fBalways override\fR values from profiles.

.SH EXAMPLES
.TP
Share for 2 hours on default ports:
.B backtunnel-share
/home/user/docs with alice@vps.example.com for 2h

.TP
Share for 1 day, using custom ports:
.B backtunnel-share
/home/user/docs with alice:vps.example.com for 1d -p 4422 -l 2222

.TP
Share using a profile, then override port:
.B backtunnel-share
/home/user/docs with @workvps for 6h -p 5500

.TP
Mount with default port and mount point:
.B backtunnel-access
/home/user/docs from alice@vps.example.com

.TP
Mount with custom port and mount point:
.B backtunnel-access
/home/user/docs from alice@vps.example.com -p 4422 -m /mnt/alice-docs

.SH NOTES
By default, \fBssh -R\fR binds to 127.0.0.1 on the remote side, limiting access to local users on the remote machine.
The client connects to \fBlocalhost:<port>\fR from the remote host.
Ensure the sharing host's sshd provides a valid SFTP subsystem for sshfs.

.SH FILES
.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.

.SH SEE ALSO
ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1)

.SH AUTHOR
Matjaž Mozetič