177 lines
4.8 KiB
Groff
177 lines
4.8 KiB
Groff
.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č
|