Last post covered the basics of the ssh command and its handy options. Yet typing out every IP address, username, and port number each time is a real hassle.

Enter the SSH Config file—a simple way to store your frequent server details and connect with a single alias, just like a bookmark.

I used to be a complete beginner who didn’t know about the config file. I’d often copy the full command into my .bashrc as an alias. Once I learned how to write a config file, I realized how clunky that approach was.

Realizing the power of SSH config

What is the SSH Config File?

The SSH Config file lets you customize how the SSH client behaves. By pre‑saving connection details—username, port, key file, etc.—you can later connect using just a short alias.

  • Location: Usually in ~/.ssh/config inside your home directory. If you just installed SSH, the file may not exist yet; you’ll need to create it.
  • Creating the file: If ~/.ssh/config is missing, create it and set permissions to 600.
    touch ~/.ssh/config
    chmod 600 ~/.ssh/config  # essential for security!

Rules for Writing the Config File

The file is plain text. Each host block starts with the Host keyword.

Basic structure

Host [alias]
    [option1] [value1]
    [option2] [value2]
    ...
  • Host [alias]: Marks the start of a block and defines the alias you’ll use. You can also put the actual hostname or IP here, and wildcards (*, ?) are allowed.
  • Indentation: Options under Host must be indented. Spaces or tabs work, but consistency is key.
  • Options: List any SSH options you’d normally pass on the command line.

Commonly used options

Option Description Example value
HostName The real server address (IP or domain) 192.168.1.100 or example.com
User Username on the remote server ubuntu, ec2-user, root
Port SSH port (default 22) 2222
IdentityFile Path to the private key ~/.ssh/id_ed25519_myserver
ForwardAgent Enable agent forwarding yes
StrictHostKeyChecking Enforce strict host key checking (recommended yes) no (temporary for testing)
PortForwarding Allow port forwarding yes
LocalForward Local port forwarding (-L equivalent) 8080 localhost:80
ServerAliveInterval Interval (seconds) to check if the server is alive 60
ServerAliveCountMax Retries before disconnecting 3

Example Config File

Let’s add a few common servers to ~/.ssh/config.

# First server: web server (alias: webserver)
Host webserver
    HostName 192.168.1.100
    User ubuntu
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_webserver  # dedicated key for the web server

# Second server: dev server (alias: devbox)
Host devbox
    HostName dev.example.com
    User developer
    IdentityFile ~/.ssh/id_rsa_dev  # RSA key
    # Forward local port 8000 to remote port 80
    LocalForward 8000 localhost:80 

# Third: all AWS EC2 instances (alias: aws-*)
Host aws-*
    User ec2-user
    IdentityFile ~/.ssh/aws_ec2_key.pem
    # Keep the connection alive
    ServerAliveInterval 60
    ServerAliveCountMax 3

# General settings for a specific IP range (alias: 10.0.0.*)
Host 10.0.0.*
    User admin
    Port 22

Explanation:

  • webserver: Connect to 192.168.1.100 as ubuntu on port 2222 using the specified key.
  • devbox: Connect to dev.example.com as developer with the given key and forward local port 8000 to remote port 80.
  • aws-*: Any alias starting with aws- inherits these settings. For example, ssh aws-prod will use ec2-user and the EC2 key.
  • 10.0.0.*: Any host in that IP range will use admin on the default port.

I’ve introduced the wildcard syntax here, but in practice I rarely use it. One‑to‑one mappings are easier to manage. When I need multiple configurations for the same server, I add separate entries and pick the right alias like choosing a dish from a menu.

Clicking the SSH button sends a magical network wave

How to Use the Config File

Once you’ve saved the settings, connecting becomes a breeze. Let’s try the examples.

1. Connect using an alias

    ssh webserver
    Enter passphrase for key '/home/youruser/.ssh/id_ed25519_webserver':
    ubuntu@webserver-ip:~ $

Internally this runs ssh -p 2222 -i ~/.ssh/id_ed25519_webserver ubuntu@192.168.1.100.

    ssh devbox
    Enter passphrase for key '/home/youruser/.ssh/id_rsa_dev':
    developer@devbox-domain:~ $

(If you also forward local port 8000, it connects to remote port 80.)

Benefits of Using a Config File

  • Convenience: Replace long, error‑prone commands with short aliases.
  • Productivity: Quickly switch between frequently accessed servers.
  • Maintainability: All connection details live in one place; updating an IP or key is trivial.
  • Security: Sensitive data (key paths, passwords) never appear in shell history.

Final Thoughts

The SSH Config file is an essential tool for any developer or system administrator who uses SSH. By leveraging it, you’ll make your SSH experience far more efficient and secure. Open ~/.ssh/config, create your own aliases, and start connecting with ease!

Check out other SSH‑related posts by searching for "ssh" in the sidebar. If you have questions, drop a comment anytime!