Saltar al contenido
Terminalia

Guía · SSH

Cómo configurar ~/.ssh/config, con ejemplos

Actualizado el · 5 min de lectura

~/.ssh/config es el fichero donde OpenSSH guarda la configuración de cada servidor, para que en vez de ssh -i ~/.ssh/id_ed25519 -p 2222 deploy@203.0.113.10 escribas ssh prod. Cada bloque empieza por Host alias y debajo van opciones como HostName, User, Port, IdentityFile o ProxyJump. Lo usan también scp, sftp, rsync y git.

En esta página

1. Crea el fichero con los permisos correctos

Terminal
mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/config && chmod 600 ~/.ssh/config
open -e ~/.ssh/config

open -e lo abre en TextEdit; sirve cualquier editor de texto plano.

2. Tu primer host

~/.ssh/config
Host prod
  HostName 203.0.113.10
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

Ahora:

Terminal
ssh prod
scp backup.sql prod:/tmp/
rsync -av ./dist/ prod:/srv/app/

Qué hace cada opción:

Qué hace cada opción
OpciónPara qué sirve
HostEl alias que escribes. Admite varios nombres y comodines (*, ?).
HostNameLa dirección real: IP o nombre DNS. Si falta, se usa el alias.
UserUsuario remoto. Si falta, tu usuario del Mac.
PortPuerto SSH. Por defecto, 22.
IdentityFileClave privada que se ofrece. Admite ~.
ProxyJumpBastión por el que saltar antes de llegar (→ guía ProxyJump).

3. Un fichero real con varios servidores

~/.ssh/config
# Específicos primero
Host prod
  HostName 203.0.113.10
  User deploy
  Port 2222

Host staging
  HostName staging.ejemplo.com
  User deploy

Host bastion
  HostName bastion.ejemplo.com
  User ubuntu

Host app-1 app-2
  HostName %h.interno.ejemplo.com
  User deploy
  ProxyJump bastion

Host github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github

# Valores por defecto al final
Host *
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
  AddKeysToAgent yes
  UseKeychain yes
  ServerAliveInterval 30

%h se sustituye por el alias (app-1 → app-1.interno.ejemplo.com).

4. Entiende el orden de lectura

OpenSSH recorre el fichero de arriba abajo y, para cada opción, se queda con el primer valor que encuentra. Por eso los hosts concretos van arriba y Host * al final: si pones Host * con User root arriba del todo, ningún User posterior tendrá efecto.

Para ver la configuración final que se aplicará a un alias:

Terminal
ssh -G prod | grep -E '^(hostname|user|port|identityfile|proxyjump) '

5. Clave con passphrase y llavero de macOS

Con AddKeysToAgent yes y UseKeychain yes (opción exclusiva del OpenSSH de Apple), la passphrase se guarda en el llavero y no te la vuelve a pedir. Para añadirla ahora:

Terminal
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Si compartes el mismo config con Linux, añade al principio IgnoreUnknown UseKeychain para que el OpenSSH de Linux no dé error.

6. Partir el fichero con Include

~/.ssh/config
Include ~/.ssh/config.d/*

Ponlo en la primera línea, antes de cualquier Host. Si lo pones dentro de un bloque Host, solo se aplica a ese bloque.

Errores comunes

  • Bad owner or permissions on ~/.ssh/config. Otros usuarios pueden escribir en el fichero. chmod 600 ~/.ssh/config.
  • Too many authentication failures. El agente ofrece todas tus claves y el servidor corta antes de llegar a la buena. Añade IdentitiesOnly yes y el IdentityFile correcto.
  • ssh: Could not resolve hostname prod. El alias no coincide con ningún Host (revisa mayúsculas y espacios) o falta HostName.
  • Una opción no hace caso. Un bloque anterior (a menudo Host * puesto arriba) ya fijó ese valor. Compruébalo con ssh -G alias.
  • Bad configuration option: usekeychain. Estás en un OpenSSH que no es el de Apple. Añade IgnoreUnknown UseKeychain al principio.
  • Host no casa con HostName. Host compara con lo que escribes en la línea de comandos, no con la IP real. ssh 203.0.113.10 no usa el bloque Host prod.

Preguntas frecuentes

¿Dónde está el fichero de configuración SSH en Mac?

El tuyo está en ~/.ssh/config, es decir, /Users/tu-usuario/.ssh/config. No existe hasta que lo creas. La configuración global del sistema está en /etc/ssh/ssh_config, pero no conviene tocarla: tu fichero personal tiene prioridad y sobrevive a las actualizaciones de macOS. En Finder, Cmd+Mayús+. muestra las carpetas ocultas como .ssh.

¿Qué diferencia hay entre Host y HostName?

Host es el nombre corto que escribes (ssh prod) y sirve para elegir qué bloque se aplica. HostName es la dirección real a la que se conecta, una IP o un nombre DNS. Si no pones HostName, OpenSSH intenta conectar al propio alias, lo que solo funciona si ese nombre existe en DNS o en /etc/hosts.

¿Funciona ~/.ssh/config con scp, rsync y git?

Sí. scp, sftp, rsync y git sobre SSH usan el mismo cliente de OpenSSH, así que leen tu ~/.ssh/config. scp fichero prod:/tmp/ o git clone github.com:usuario/repo.git aplican el usuario, el puerto, la clave y el ProxyJump del alias. También los clientes gráficos que usan el OpenSSH del sistema.

Guías relacionadas