sysadminmatmoz
fcbd6514cc
Introduce `backtunnel-authorize` for managing restricted SFTP-only keys, and update `backtunnel-share` to support temporary accessor key authorization via `--allow-key` and `--allow-known`. Extend bash completion with profile, accessor, and SSH host suggestions. Revamp README sections to include updated workflows, quick starts, and key management details.
137 lines
4.3 KiB
Groff
137 lines
4.3 KiB
Groff
.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č
|