SSH Config

~/.ssh/config — your remote address book

Without config, every ssh command needs the full host, user, port, key path. ~/.ssh/config turns ssh -i ~/.ssh/work_id -p 2222 alice@server.example.com into ssh work. Same for scp, rsync, and any tool that uses ssh under the hood.

The shape

Host work
  HostName server.example.com
  User alice
  Port 2222
  IdentityFile ~/.ssh/work_id_ed25519
  IdentitiesOnly yes

Host *.internal
  User root
  ProxyJump bastion.internal

Indent the directives. Patterns (*.internal, 10.0.*) match by host alias. Order matters — earlier blocks win on conflict.

Common directives

IdentityFile ~/.ssh/foo — which key to use.
IdentitiesOnly yes — try only that key (avoids ssh-agent spamming all your keys until the server locks you out).
ProxyJump bastion — go through a jump host.
ForwardAgent yes — forward your local agent (use carefully).
LocalForward 5900 localhost:5900 — auto-tunnel on connect.
ControlMaster auto, ControlPath ~/.ssh/cm-%r@%h:%p — share a single connection between commands. Speeds up rsync loops massively.

Permissions matter

~/.ssh must be 700, files inside 600. Loose permissions make ssh refuse to use the key ("Permissions are too open"). One chmod 700 ~/.ssh; chmod 600 ~/.ssh/* after cloning a dotfiles repo saves an hour of debugging.

Test fast

ssh -T host tries to authenticate without opening a shell. ssh -v host shows every step the client takes. Use these for debugging.

SSH configuration is first value wins

For each parameter, OpenSSH uses the first obtained value, so put specific Host blocks before broad defaults and inspect the effective result with ssh -G host. ssh -T disables pseudo-terminal allocation; it is not an authentication-only mode. Tighten permissions only on the exact private key or configuration file whose contract requires it.

Agent forwarding is not key copying

The remote host cannot read the private key file, but a process there may ask the forwarded agent to sign while the connection is open. Enable forwarding only for a trusted hop that actually needs it.

Code

Bootstrap an SSH config·bash

mkdir -p ~/.ssh && chmod 700 ~/.ssh
cat > ~/.ssh/config <<'EOF'
Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 1h

Host server
  HostName 192.168.1.10
  User you_username
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
EOF
chmod 600 ~/.ssh/config