SSH Client Custom Connection Options Setup

This guide shows you how to configure custom connection options for your SSH client, letting you define aliases, set specific ports, use custom identity files, and enable connection keep-alives without typing long commands every time. You’ll edit your SSH configuration file to create reusable profiles for different servers.

What You’ll Need

• A computer with an SSH client installed (OpenSSH is standard on Linux, macOS, and Windows 10/11).
• Access to your user’s home directory (to create or edit ~/.ssh/config).
• Basic knowledge of a text editor (like nano, vim, or Notepad).
• The hostname or IP address of the server you want to connect to.

Step-by-Step

1. Open or create your SSH config file. On Linux/macOS, open a terminal and run: nano ~/.ssh/config. If the file doesn’t exist, this creates it. On Windows (OpenSSH), the path is C:\Users\YourName\.ssh\config – create the .ssh folder if needed.
2. Set correct permissions (Linux/macOS only). Run chmod 600 ~/.ssh/config to ensure only you can read/write the file. SSH will ignore the file if permissions are too open.
3. Add your first host block. Each server gets a block starting with Host followed by an alias you choose. For example:

   Host myserver
       HostName example.com
       User myusername
       Port 2222
       IdentityFile ~/.ssh/mykey

   The Host line is the short name you’ll type; HostName is the actual domain/IP; User is your login; Port overrides the default 22; IdentityFile points to your private key.

4. Add connection keep-alive options. To prevent idle disconnects, add these lines inside the host block:

   ServerAliveInterval 60
   ServerAliveCountMax 3

   This sends a keep-alive packet every 60 seconds and disconnects after 3 missed responses.

5. Use wildcards for groups of servers. If multiple servers share settings, use a pattern like Host *.example.com or Host prod-*. Settings in a more specific block override wildcards.
6. Set default options for all hosts. Add a block at the top: Host * with options like Compression yes or ForwardAgent no. This applies to every connection unless overridden.
7. Enable SSH agent forwarding (use carefully). Add ForwardAgent yes if you need to hop from one server to another without re-entering your passphrase. Only enable this for trusted hosts.
8. Test your configuration. Save the file and run ssh myserver. If it connects, your config works. If not, check the error messages and your syntax.
9. Verify with verbose mode. Run ssh -v myserver to see which config file is being read and which options are applied. This helps debug unexpected behavior.

Common Mistakes

• Wrong file permissions: On Unix systems, if your config or key files are readable by others, SSH will refuse to use them with a warning like “Bad permissions”. Fix with chmod 600 on config and keys.
• Using spaces instead of tabs or misaligned indentation: SSH config is whitespace-sensitive but not strict about tabs vs spaces; however, consistent indentation (spaces are fine) is required. A common error is putting options on the same line as Host.
• Forgetting the Host line: Every block must start with Host. If you only have HostName, SSH won’t recognize it as a new block.
• Overwriting the default port: If you set Port in a Host * block, it applies to all hosts, which might break connections to servers that use port 22. Override per host.
• Using a relative path for IdentityFile: Relative paths are resolved from the user’s home directory, not the current directory. Use ~/.ssh/key or an absolute path.
• Quoting values that don’t need quotes: Quotes are only needed for values with spaces. Adding them elsewhere can cause parsing errors.

Tips

• Use descriptive aliases: Name hosts by function (e.g., web-prod, db-backup) to make commands readable.
• Keep backups: Before major edits, copy your config: cp ~/.ssh/config ~/.ssh/config.bak.
• Use Include to split configs: If you have many hosts, put them in separate files and add Include ~/.ssh/config.d/* at the top of your main config.
• Leverage Match for dynamic conditions: You can use Match host example.com user admin to apply options only when both conditions are true.
• Test with -G: Run ssh -G myserver to print the effective configuration for that host without connecting. This shows exactly which options will be used.

Troubleshooting

Connection refused or timeout: Check the HostName and Port values. Ensure the server is reachable (ping) and the port is open (use nc -zv host port).

Permission denied (publickey): Verify the IdentityFile path is correct and the key file has permissions 600. Also confirm the public key is installed on the server’s ~/.ssh/authorized_keys.

Config not being read: Run ssh -v and look for the line “Reading configuration data …”. If it doesn’t show your file, you may be using a different path or the file is not named config (case-sensitive on Linux/macOS).

Option not applied: Check for typos in option names (e.g., ServerAliveInterval not ServerAliveInterval). Use ssh -G to see the resolved values.

Bad owner or permissions: SSH prints a clear error. Run chmod 600 ~/.ssh/config and chmod 700 ~/.ssh (the directory should be 700).

Cannot connect after adding wildcard: A wildcard may be overriding a specific host. Move the specific host block after the wildcard, or use a more specific pattern.

Frequently Asked Questions

Can I use the same config file for both work and personal servers?

Yes, just add multiple Host blocks. Use Include to separate them into different files if you prefer.

How do I set a different username for a specific host?

Inside that host’s block, add User yourname. This overrides the default username.

What does ServerAliveInterval do exactly?

It sends a packet to the server every specified number of seconds to keep the connection alive. If the server doesn’t respond after ServerAliveCountMax times, SSH disconnects.

Can I use environment variables in the config file?

No, SSH config does not expand environment variables. Use absolute paths or ~ for home directory.

Why is my config file being ignored?

Common reasons: wrong file location, incorrect permissions, or a syntax error earlier in the file that prevents parsing. Check with ssh -v and ssh -G.

Is it safe to use ForwardAgent?

It’s safe only if you trust the remote host completely, because the remote user can access your local SSH agent. Disable it by default and enable per trusted host.

Related

• Vivo T4x vs iQOO Z10: Specs Compared
• Belfast vs Derry: Indian Startup Office Choice
• Galaxy A37 vs Redmi Note 17 Pro 5G: Which Fits?