120 lines
3.1 KiB
Markdown
120 lines
3.1 KiB
Markdown
# SSH Utility - Smart SSH Connection Manager
|
|
|
|
A transparent SSH wrapper that automatically chooses between local and remote connections based on network connectivity.
|
|
|
|
## What it does
|
|
|
|
This utility acts as a drop-in replacement for the `ssh` command that intelligently routes connections:
|
|
|
|
- When you type `ssh desktop`, it automatically checks if your local network is available
|
|
- If local: connects via `desktop-local` (faster local connection)
|
|
- If remote: connects via `desktop` (Tailscale/VPN connection)
|
|
- All other SSH usage passes through unchanged (`ssh --help`, `ssh user@host`, etc.)
|
|
|
|
## Installation
|
|
|
|
The utility is automatically compiled and installed to `~/.local/bin/ssh` via Ansible when you run your dotfiles setup.
|
|
|
|
## Configuration
|
|
|
|
1. Copy the example config:
|
|
```bash
|
|
mkdir -p ~/.config/ssh-util
|
|
cp ~/.dotfiles/config/ssh-util/config.yaml ~/.config/ssh-util/
|
|
```
|
|
|
|
2. Edit `~/.config/ssh-util/config.yaml` to match your setup:
|
|
```yaml
|
|
smart_aliases:
|
|
desktop:
|
|
primary: "desktop-local" # SSH config entry for local connection
|
|
fallback: "desktop" # SSH config entry for remote connection
|
|
check_host: "192.168.86.22" # IP to ping for connectivity test
|
|
timeout: "2s" # Ping timeout
|
|
```
|
|
|
|
3. Ensure your `~/.ssh/config` contains the referenced host entries:
|
|
```
|
|
Host desktop
|
|
HostName mennos-cachyos-desktop
|
|
User menno
|
|
Port 400
|
|
ForwardAgent yes
|
|
AddKeysToAgent yes
|
|
|
|
Host desktop-local
|
|
HostName 192.168.86.22
|
|
User menno
|
|
Port 400
|
|
ForwardAgent yes
|
|
AddKeysToAgent yes
|
|
```
|
|
|
|
## Usage
|
|
|
|
Once configured, simply use SSH as normal:
|
|
|
|
```bash
|
|
# Smart connection - automatically chooses local vs remote
|
|
ssh desktop
|
|
|
|
# All other SSH usage works exactly the same
|
|
ssh --help
|
|
ssh --version
|
|
ssh user@example.com
|
|
ssh -L 8080:localhost:80 server
|
|
```
|
|
|
|
## How it works
|
|
|
|
1. When you run `ssh <alias>`, the utility checks if `<alias>` is defined in the smart_aliases config
|
|
2. If yes, it pings the `check_host` IP address
|
|
3. If ping succeeds: executes `ssh <primary>` instead
|
|
4. If ping fails: executes `ssh <fallback>` instead
|
|
5. If not a smart alias: passes through to real SSH unchanged
|
|
|
|
## Troubleshooting
|
|
|
|
### SSH utility not found
|
|
Make sure `~/.local/bin` is in your PATH:
|
|
```bash
|
|
echo $PATH | grep -o ~/.local/bin
|
|
```
|
|
|
|
### Config not loading
|
|
Check the config file exists and has correct syntax:
|
|
```bash
|
|
ls -la ~/.config/ssh-util/config.yaml
|
|
cat ~/.config/ssh-util/config.yaml
|
|
```
|
|
|
|
### Connectivity test failing
|
|
Test manually:
|
|
```bash
|
|
ping -c 1 -W 2 192.168.86.22
|
|
```
|
|
|
|
### Falls back to real SSH
|
|
If there are any errors loading config or parsing, the utility safely falls back to executing the real SSH binary at `/usr/bin/ssh`.
|
|
|
|
## Adding more aliases
|
|
|
|
To add more smart aliases, just extend the config:
|
|
|
|
```yaml
|
|
smart_aliases:
|
|
desktop:
|
|
primary: "desktop-local"
|
|
fallback: "desktop"
|
|
check_host: "192.168.86.22"
|
|
timeout: "2s"
|
|
|
|
server:
|
|
primary: "server-local"
|
|
fallback: "server-remote"
|
|
check_host: "192.168.1.100"
|
|
timeout: "1s"
|
|
```
|
|
|
|
Remember to create the corresponding entries in your `~/.ssh/config`.
|