dotfiles/config/ansible/tasks/global/utils/smart-ssh

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:

   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:

   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:

# 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:

echo $PATH | grep -o ~/.local/bin

Config not loading

Check the config file exists and has correct syntax:

ls -la ~/.config/ssh-util/config.yaml
cat ~/.config/ssh-util/config.yaml

Connectivity test failing

Test manually:

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:

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.