SSH Config Cheatsheet
SSH client config directives at a glance: Host and Match patterns, keys, jump hosts, keepalives, multiplexing, port forwarding, host key checking, and tokens for ~/.ssh/config.
The SSH client config file stores per-host settings so that ssh myserver replaces a long command with flags for the user, port, key, and jump host. This cheatsheet lists the ~/.ssh/config directives you use most often, how OpenSSH matches and applies them, and the commands that show the settings ssh actually uses.
File Locations
ssh reads the command line first, then your config, then the system config.
| Path | Description |
|---|---|
~/.ssh/config | Per-user client config |
/etc/ssh/ssh_config | System-wide client config for every user |
/etc/ssh/ssh_config.d/*.conf | System drop-ins, loaded by Include on Ubuntu and Debian |
chmod 600 ~/.ssh/config | Recommended permissions; ssh rejects a file others can write |
ssh -F ~/alt-config host | Use a different config file and skip the defaults |
ssh -F none host | Ignore every config file |
Inspect the Effective Config
Check what ssh will use before you connect.
| Command | Description |
|---|---|
ssh -G host | Print every option that applies to host, then exit |
ssh -G host | grep -i proxyjump | Check one option |
ssh -v host | Show which config lines and keys are applied while connecting |
ssh -o User=admin host | Override a config value for one connection |
ssh -T git@github.com | Test a host without opening a shell |
Host Patterns
A Host line starts a block that runs until the next Host or Match line.
| Pattern | Matches |
|---|---|
Host web | The alias web only |
Host web1 web2 db | Any of the listed names |
Host *.example.com | Every host under example.com |
Host 192.168.1.? | Single-character wildcard |
Host *.example.com !legacy.example.com | All but the negated host |
Host * | Every host; put it at the end for defaults |
The first value wins for most directives; repeated IdentityFile entries accumulate. Put specific blocks above general ones and Host * last.
Match Blocks
Match applies a block based on conditions, not just the name.
| Directive | Description |
|---|---|
Match host db* | Hostname after HostName is applied |
Match originalhost db* | Name as typed on the command line |
Match user root | Remote user |
Match localuser alice | Local account running ssh |
Match host *.corp exec "nc -z vpn.corp 22" | Apply only when a command exits 0 |
Match all | Close a conditional block and match everything again |
Connection Basics
The directives most host blocks need.
| Directive | Description |
|---|---|
HostName 203.0.113.10 | Real hostname or IP behind the alias |
User admin | Remote login name |
Port 2222 | Remote port; default is 22 |
AddressFamily inet | Force IPv4 (inet6 for IPv6) |
ConnectTimeout 10 | Give up after 10 seconds |
ConnectionAttempts 3 | Retry the connection before failing |
Compression yes | Compress traffic on slow links |
Keys and Authentication
Pick the key per host and stop ssh from trying every key it has.
| Directive | Description |
|---|---|
IdentityFile ~/.ssh/id_ed25519_work | Private key for this host |
IdentitiesOnly yes | Offer only the configured keys, not every agent key |
AddKeysToAgent yes | Add the key to the running agent after first use |
CertificateFile ~/.ssh/id_ed25519-cert.pub | SSH certificate to present |
PreferredAuthentications publickey | Try public-key authentication only |
PasswordAuthentication no | Disable password authentication; keyboard-interactive prompts can still occur |
KbdInteractiveAuthentication no | Disable keyboard-interactive authentication, including its password prompts |
IgnoreUnknown UseKeychain | Skip options that this ssh build does not know |
UseKeychain yes | macOS only: store key passphrases in the keychain |
Jump Hosts
Reach private hosts through a bastion.
| Directive | Description |
|---|---|
ProxyJump bastion | Connect through the bastion alias |
ProxyJump admin@bastion.example.com:2222 | Jump host with user and port |
ProxyJump bastion1,bastion2 | Chain several jump hosts in order |
ProxyJump none | Disable jumping; place this before a matching broader block |
ProxyCommand ssh -W %h:%p bastion | Older equivalent of ProxyJump |
ssh -J bastion internal | Same jump from the command line |
Keepalives
Stop idle sessions from being dropped by NAT or firewalls.
| Directive | Description |
|---|---|
ServerAliveInterval 60 | Send a keepalive after 60 seconds without server data |
ServerAliveCountMax 3 | Disconnect after 3 unanswered keepalives |
TCPKeepAlive yes | TCP-level keepalives; on by default |
Multiplexing
Reuse one TCP connection for later sessions to the same host.
| Directive or command | Description |
|---|---|
ControlMaster auto | Open a master connection, or reuse an existing one |
ControlPath ~/.ssh/cm-%C | Socket path; %C keeps it short and unique |
ControlPersist 10m | Keep the master open 10 minutes after the last session |
ssh -O check host | Check whether a master connection is running |
ssh -O exit host | Close the master connection |
Port Forwarding
Set up tunnels every time you connect to a host.
| Directive | Description |
|---|---|
LocalForward 8080 localhost:80 | Local port 8080 to port 80 on the remote side |
LocalForward 3307 db.internal:3306 | Reach a host that only the server can see |
RemoteForward 9000 localhost:3000 | Remote port 9000 to local port 3000 |
DynamicForward 1080 | SOCKS proxy on local port 1080 |
ExitOnForwardFailure yes | Abort if a forward cannot be set up |
ForwardAgent yes | Forward your agent; set it only for trusted hosts |
ForwardX11 yes | Forward X11 for GUI applications |
Host Key Checking
Control how ssh treats new and changed server keys.
| Directive | Description |
|---|---|
StrictHostKeyChecking ask | Prompt for new hosts; the default |
StrictHostKeyChecking accept-new | Trust new hosts, still refuse changed keys |
StrictHostKeyChecking yes | Refuse any host not in known_hosts |
UserKnownHostsFile ~/.ssh/known_hosts_lab | Separate known_hosts file for a group of hosts |
UserKnownHostsFile /dev/null | Do not record keys; for throwaway VMs only |
HashKnownHosts yes | Hash hostnames written to known_hosts |
UpdateHostKeys yes | Accept additional keys the server announces |
Session and Environment
Change what happens after you log in.
| Directive | Description |
|---|---|
RemoteCommand tmux new -A -s main | Run a command instead of a login shell |
RequestTTY yes | Allocate a terminal; needed with RemoteCommand for interactive tools |
SetEnv APP_ENV=prod | Send a variable; the server must allow it with AcceptEnv |
SendEnv LANG LC_* | Pass local variables by name |
LogLevel ERROR | Hide warnings; DEBUG for troubleshooting |
Include ~/.ssh/config.d/* | Load more files; put it at the top of the file |
Tokens
Expanded in ControlPath, IdentityFile, RemoteCommand, and similar directives. Supported tokens vary by directive.
| Token | Expands To |
|---|---|
%h | Remote hostname after HostName |
%n | Hostname as typed on the command line |
%p | Remote port |
%r | Remote user |
%u | Local user |
%d | Local home directory |
%C | Hash of local host, remote host, port, remote user, and jump-host setting |
%% | A literal % |
ProxyCommand accepts only %%, %h, %n, %p, and %r.
Troubleshooting
| Problem | Check |
|---|---|
Bad owner or permissions on ~/.ssh/config | Check ownership with ls -l ~/.ssh/config; the owner must be you or root. Fix incorrect ownership, then run chmod 600 ~/.ssh/config |
Bad configuration option | Typo, or an option this ssh version lacks; see man ssh_config |
| Option is ignored | An earlier block set it first; check ssh -G host |
Too many authentication failures | Add IdentitiesOnly yes and an IdentityFile |
Permission denied (publickey) | ssh -v host and look for Offering public key |
too long for Unix domain socket | Shorten ControlPath; use %C instead of %r@%h:%p |
Related Guides
Use these articles for full SSH client workflows.
| Guide | Description |
|---|---|
Using the SSH Config File | Host blocks, patterns, precedence, and examples |
SSH Command in Linux | ssh options and connection examples |
How to Set Up SSH Tunneling | Local, remote, and dynamic port forwarding |
SSH Folder Files and Permissions | What lives in ~/.ssh and the correct modes |
SSH Cheatsheet | ssh, keys, agent, scp, and sftp commands |