Add profile support to BackTunnel with defaults, named remotes, and seamless integration across CLI, GUI, and documentation
This commit is contained in:
118
man/backtunnel.1
118
man/backtunnel.1
@@ -1,51 +1,53 @@
|
||||
.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
|
||||
backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and access (with profiles)
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B backtunnel-share
|
||||
/path/to/folder with remoteuser:remotehost for <duration> [options]
|
||||
/path/to/folder with {remoteuser:remotehost|remoteuser@remotehost|@profilename} for <duration> [options]
|
||||
|
||||
.B backtunnel-access
|
||||
/path/to/folder from remoteuser:remotehost [options]
|
||||
/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.
|
||||
The sharing ends automatically after the given \fIduration\fR via \fBtimeout\fR.
|
||||
\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.
|
||||
|
||||
With the \fB--invite\fR option, \fBbacktunnel-share\fR prints a ready-to-copy access command for the remote user,
|
||||
which can be pasted directly into a chat or terminal. The invite can also be rendered as a QR code or written to a file.
|
||||
|
||||
\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).
|
||||
\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).
|
||||
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).
|
||||
Local sshd port to forward to (default: 22). May be provided via profile.
|
||||
|
||||
.TP
|
||||
.B -i, --invite
|
||||
Print a ready-to-copy invite command for the remote user.
|
||||
Print a ready-to-copy access command for the remote side.
|
||||
|
||||
.TP
|
||||
.B --invite-mount <PATH>
|
||||
Mount point suggested in the invite (default: /mnt/remote-rssh).
|
||||
Suggested mount point included in the invite text (default: /mnt/remote-rssh). May be provided via profile.
|
||||
|
||||
.TP
|
||||
.B --invite-file <FILE>
|
||||
Also write the invite text (including unmount hint) to the given file.
|
||||
Write the invite text (including unmount hint) to the given file.
|
||||
|
||||
.TP
|
||||
.B --qr
|
||||
Render the invite as a terminal QR code (requires \fBqrencode\fR).
|
||||
Additionally render the invite as a QR code (requires \fBqrencode\fR).
|
||||
|
||||
.TP
|
||||
.B -h, --help
|
||||
Show usage.
|
||||
|
||||
.SS backtunnel-access options
|
||||
.TP
|
||||
@@ -65,9 +67,65 @@ Path to share (server) or to mount (client).
|
||||
.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.
|
||||
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
|
||||
@@ -81,14 +139,9 @@ Share for 1 day, using custom ports:
|
||||
/home/user/docs with alice:vps.example.com for 1d -p 4422 -l 2222
|
||||
|
||||
.TP
|
||||
Share for 2 hours and print an invite:
|
||||
Share using a profile, then override port:
|
||||
.B backtunnel-share
|
||||
/home/user/docs with alice@vps.example.com for 2h -i
|
||||
|
||||
.TP
|
||||
Share with QR invite:
|
||||
.B backtunnel-share
|
||||
/home/user/docs with alice@vps.example.com for 2h -i --qr
|
||||
/home/user/docs with @workvps for 6h -p 5500
|
||||
|
||||
.TP
|
||||
Mount with default port and mount point:
|
||||
@@ -103,12 +156,21 @@ Mount with custom port and mount point:
|
||||
.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.
|
||||
|
||||
The invite feature is intended for convenience: copy-paste the printed command into chat for the remote user.
|
||||
Unmount with \fBfusermount -u <mountpoint>\fR after use.
|
||||
.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), qrencode(1), fusermount(1)
|
||||
ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1)
|
||||
|
||||
.SH AUTHOR
|
||||
Matjaž Mozetič
|
||||
|
||||
Reference in New Issue
Block a user