You are typing the same SSH command again
You are typing ssh -i ~/.ssh/prod_key -p 2222 deploy@192.168.1.50 for the third time today. Your muscle memory types the wrong port. The connection hangs. You kill it, check the IP, and start over. You have five servers. You are copying and pasting from a notes file. One paste error and you lock yourself out or deploy to staging instead of production.
The SSH config file exists to stop this cycle. It turns a wall of flags into a single word. You define the host once. You type ssh prod and it works. The file lives in your home directory. It is plain text. It survives reboots. It travels with you if you sync your dotfiles.
What SSH config actually does
SSH reads configuration files in a specific order when you run a command. It starts with the system-wide file, moves to your user file, and applies settings based on the host pattern you provide. Think of the config file as a lookup table. You provide a nickname. SSH matches that nickname to a block of settings. It merges those settings with defaults and executes the connection.
The file is just text. The SSH client parses it and translates the directives into the flags you would otherwise type manually. This happens every time you connect. The client does the heavy lifting so you don't have to memorize IPs or key paths. The config also supports patterns, jump hosts, and conditional logic that would be painful to type on the command line every time.
Create and secure the config file
Create the config file in your home directory and lock down permissions so SSH accepts it. SSH enforces strict permissions. It will ignore the file if other users can read it. This prevents credential leakage on shared machines.
mkdir -p ~/.ssh # Ensure the directory exists before creating files
touch ~/.ssh/config # Create the config file if it is missing
chmod 700 ~/.ssh # SSH requires the directory to be private
chmod 600 ~/.ssh/config # SSH refuses to read config files readable by others
The system-wide config lives in /etc/ssh/ssh_config. Packages can drop snippets in /etc/ssh/ssh_config.d/. Your user file in ~/.ssh/config takes precedence for your account. Edit your user file. Never edit /etc/ssh/ssh_config directly unless you are managing the whole machine.
Run chmod 600 immediately. SSH ignores the file if the permissions are wrong and gives a silent failure.
Define hosts and defaults
Define a host block with the essential connection details to replace a long command line. Each block starts with the Host keyword followed by a nickname. Indent the directives that apply to that host. The nickname is what you type after ssh. The directives map to the flags you would otherwise use.
Host prod-web
HostName 192.168.1.50 # The actual IP or domain of the remote server
User deploy # The username to log in as on the remote side
Port 2222 # The port number if it is not the default 22
IdentityFile ~/.ssh/prod_key # Path to the private key for authentication
IdentitiesOnly yes # Prevent SSH from trying other keys in the agent
Add a wildcard block to set safe defaults for every connection you make. The Host * pattern matches everything. Place it at the end of the file. SSH reads top to bottom. The first match wins. A wildcard at the top swallows all subsequent blocks.
Host *
ServerAliveInterval 60 # Send a keep-alive packet every 60 seconds
ServerAliveCountMax 3 # Disconnect after 3 missed keep-alives
AddKeysToAgent yes # Automatically add keys to ssh-agent if running
StrictHostKeyChecking ask # Prompt on first connect instead of auto-accepting
VisualHostKey yes # Show the key fingerprint visually during connection
When you have multiple keys loaded in ssh-agent, the client might try the wrong one and fail authentication. IdentitiesOnly yes forces SSH to use only the key specified in IdentityFile. This prevents Permission denied (publickey) errors when the agent holds keys for unrelated hosts.
Trust the order. Top-down evaluation catches most config bugs.
Jump hosts and proxies
Configure a jump host to reach internal servers through a bastion without manual tunneling. The ProxyJump directive tells SSH to connect to an intermediate host first, then forward the connection to the final destination. You only type one command. SSH handles the chain.
Host bastion
HostName jump.example.com
User admin
IdentityFile ~/.ssh/bastion_key
Host internal-db
HostName 10.0.0.20
User dbadmin
ProxyJump bastion # Route this connection through the bastion host
IdentityFile ~/.ssh/db_key # Key for the internal database server
Now ssh internal-db connects to bastion, authenticates, and then connects to internal-db. You see a single prompt. The local terminal session represents the final host.
Set up a SOCKS proxy for browsing through a remote network. DynamicForward opens a port on your local machine that acts as a SOCKS5 proxy. Traffic sent through this proxy travels over the SSH tunnel to the remote host, which then fetches the data. This is useful for accessing internal web services from your browser.
Host vpn-proxy
HostName remote.example.com
User alice
DynamicForward 1080 # Open a SOCKS5 proxy on localhost port 1080
ExitOnForwardFailure yes # Kill the connection if the port bind fails
ServerAliveInterval 30 # Keep the tunnel alive more aggressively
Run ssh vpn-proxy in the background. Configure your browser to use socks5h://localhost:1080. The browser traffic flows through the tunnel. Use ProxyJump for server access. Use DynamicForward when you need to browse an internal network from your browser.
Verify the configuration
Check the effective configuration and debug connection issues before committing to a session. SSH provides flags to inspect the resolved settings and trace the handshake. Use these to catch errors without opening a full connection.
ssh -G prod-web # Print the resolved configuration for the host
ssh -v prod-web # Run a verbose connection to see key exchange and auth steps
The -G flag outputs the final configuration after all patterns and defaults are applied. It shows the exact values SSH will use. This is the best way to verify that ProxyJump or IdentityFile is set correctly. The -v flag enables verbose mode. It prints debug information about the connection process, including key offers and server responses. Add more v flags for deeper debugging.
Run ssh -G before you connect. It reveals permission errors and wrong keys without opening a session.
Common pitfalls and errors
SSH stops reading the config file if permissions are loose. You will see this error in the terminal:
Permissions 0644 for '/home/user/.ssh/config' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Fix the mode with chmod 600 ~/.ssh/config. The error mentions private keys, but it applies to the config file as well. SSH treats the config file as sensitive because it can contain key paths and host settings.
The config file evaluates top to bottom. The first matching value for a directive wins. Put specific hosts before wildcards. If you put Host * at the top, it captures everything and ignores the blocks below. This is the most common mistake. Specific blocks must appear before general blocks.
Use Include to split large configs across multiple files. This keeps the main file clean and allows modular organization.
Include ~/.ssh/conf.d/*.conf # Load all config snippets from the conf.d directory
Create the directory and add files. SSH merges the included files as if they were part of the main config. This pattern matches the convention used by systemd and NetworkManager on Fedora. It scales better than a single monolithic file.
Trust the package manager. Manual file edits drift, snapshots stay.
When to use SSH config features
Use ~/.ssh/config when you manage multiple servers and want to reduce typing errors. Use ProxyJump when you need to reach private networks through a single public entry point. Use DynamicForward when you need to browse internal web services through a remote tunnel. Use Include when your config grows past twenty hosts and needs to be split across files. Use ssh -G when you suspect a setting is being overridden or ignored. Stick to command-line flags when you are connecting to a host once and never again.