Add accessor key authorization and enhance completion logic
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.
This commit is contained in:
198
man/backtunnel.1
198
man/backtunnel.1
@@ -1,7 +1,7 @@
|
||||
.TH backtunnel 1 "September 2025" "1.2" "BackTunnel – Reverse SSH Sharing Toolkit"
|
||||
.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)
|
||||
backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and access (with profiles, temporary key authorization)
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B backtunnel-share
|
||||
@@ -14,151 +14,56 @@ backtunnel-share, backtunnel-access \- Secure reverse SSH folder sharing and acc
|
||||
\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).
|
||||
|
||||
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). May be provided via profile.
|
||||
|
||||
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). May be provided via profile.
|
||||
|
||||
Local sshd port to forward to (default: 22).
|
||||
.TP
|
||||
.B -i, --invite
|
||||
Print a ready-to-copy access command for the remote side.
|
||||
|
||||
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>
|
||||
Suggested mount point included in the invite text (default: $HOME/remote-rssh). May be provided via profile.
|
||||
|
||||
Mount point suggested in invite (default: \fI$HOME/remote-rssh\fR).
|
||||
.TP
|
||||
.B --invite-file <FILE>
|
||||
Write the invite text (including unmount hint) to the given file.
|
||||
|
||||
Also write the invite text (with unmount hint) to FILE.
|
||||
.TP
|
||||
.B --qr
|
||||
Additionally render the invite as a QR code (requires \fBqrencode\fR).
|
||||
|
||||
Also print a QR code (requires \fBqrencode\fR).
|
||||
.TP
|
||||
.B -h, --help
|
||||
Show usage.
|
||||
.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: $HOME/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.
|
||||
Local mount point for sshfs (default: \fI$HOME/remote-rssh\fR).
|
||||
|
||||
.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:
|
||||
Profiles allow you to use \fB@name\fR instead of \fIuser@host\fR and to set defaults.
|
||||
|
||||
.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=$HOME/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
|
||||
The configuration search order is:
|
||||
.TP
|
||||
\fB~/.config/backtunnel/profiles.ini\fR
|
||||
Per-user configuration file containing defaults and named profiles.
|
||||
@@ -169,8 +74,63 @@ System-wide default profiles (editable by admins).
|
||||
\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)
|
||||
ssh(1), sshfs(1), timeout(1), autossh(1), fusermount(1),
|
||||
\fBbacktunnel-keys\fR(1), \fBbacktunnel-auth-setup\fR(1)
|
||||
|
||||
.SH AUTHOR
|
||||
Matjaž Mozetič
|
||||
|
||||
Reference in New Issue
Block a user