Skip to Main Content

Mihomo SSH Config Alias Support

· 阅读需 3 分钟

🔗 Project Info​

  • Fork Repository: https://github.com/iuin8/mihomo
  • Branch: (Make sure to see branches that contain the ssh-config-alias function, e.g. ssh_system_v1.19.17)
  • Core file: adapter/outbound/ssh.go, adapter/outbound/ssh_system.go

📖 Needs background​

In a complex network environment, users often maintain a full set of SSH profiles (~/.ssh/config).These configurations may contain：

  1. ProxyJump (dashboard)：requires one or more skippers to access the target inner web server.
  2. ProxyCommand：uses third-party authentication tools (e.g. Cloudflare Access, AWS SSM).
  3. IdentityFile：uses different key files for different hosts.
  4. Host alias：uses short aliases instead of long IP or domain names.

The original Mihomo SSH adapter uses the Go language native SSH library and cannot use these system level configurations directly, resulting in the user having to manually convert complex springboard logic to the Dialer Proxy chain. The configuration is onerous and does not support some advanced instructions (such as the special ProxyCommand).

Target：allows Mihomo to "loan" system SSH client directly, simply fill in a host alias (e.g. my-server), the remaining authentication, skip to system SSH handling.

✨ Features​

Full SSH Config support​

Build tunnels by calling the system ssh command, Mihomo can support all instructions： that support SSH clients

  • ✅ ProxyJump / JumpHost
  • ✅ ProxyCommand (support cloudfled, nc etc.)
  • ✅ IdentityFile, User, Port and so on
  • ✅ advanced configuration logic like Match, Include

2. Smart user switching (sudo -u)​

Mihomo usually runs with root permissions (for TUN mode and so on) while the user's SSH configuration is located in the regular user directory.This feature implements：

  • Automatically detect or specify actual users.
  • Use sudo -u <user> -i to switch identity to perform SSH.
  • **-i parameters** ensure that the complete login environment of the user (PATH), ensures that the cloudflared` command can be found.

Zero configuration key​

There is no need to fill the private key content in the Mihomo configuration file. It will automatically read ~/.ssh/id_rsa or the IdentityFile specified in the configuration.

🚀 Usage method​

Parameter Description​

FieldsNote
typemust be ssh
serverKey：Fill Host in ~/.ssh/config`
portNote：fills the target serviceinner listening ports (usually 22).
⚠️ Don't fill the map port in ~/.ssh/config.
use-ssh-config-aliasSet to true to enable this feature
ssh-userSpecify the username of the local SSH command (your macOS/Linux username)

Configuration Example​

Scene 1：Base Jump (ProxyJump)​

SSH Config (~/.ssh/config):

Host base
  HostName 1.2.3.4
  User admin

Post internal-db
  HostName 10.0.5
  User root
  ProxyJump base # automatic bastion jump forward

Mihomo Configuration:

proxies:
  - name: "Internal-DB-SSH"
    type: ssh
    server: "internal-db" # Direct Alias
    port: 22 # Internal SSH port
    use-ssh-config-alias: true
    ssh-user: "your-username" #

Scene 2：Cloudflare Access (ProxyCommand)​

*SSH Config:

Host my-cf-server
  HostName ssh.example.com
  User root
  # Requires cloudfled command in PATH
  ProxyCommand cloudflowed access ssh --hostname %h

Mihomo Configuration:

proxies:
  - name: "CF-SSH"
    type: ssh
    server: "my-cf-server"
    port: 22
    use-ssh-config-alias: true
    ssh-user: "your-username"

🛠️ Summary of rationale​

Mihomo will perform a command similar to： at the bottom after receiving a connection request

sudo -u your-username -i ssh -W localhost:22 my-host-alias

This command creates a TCP tunnel for standard input/output to a target SSH port.Mihomo then handshake his own SSH protocol on this tunnel, and set up proxy connections.