feat: added a ssh utility that supports smart-aliases and background ssh

tunnels

config/ansible/tasks/global/utils/smart-ssh/README.md

@@ -0,0 +1,119 @@
+# 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`.