How SSH Resolves Conflicting Configs on Ubuntu

When managing SSH connections on Ubuntu Linux, configuration settings can be defined globally for all users or customized for individual user accounts. This article explains how the OpenSSH client resolves conflicting settings between the system-wide configuration and user-specific configurations, detailing the strict order of precedence and the “first match wins” rule that governs how options are applied.

The Rule of Precedence: First Match Wins

The OpenSSH client resolves conflicts using a simple but strict rule: the first value obtained for a given configuration parameter is the one that is used. Once a parameter (such as a port, identity file, or username) is set for a host, any subsequent definitions of that same parameter are completely ignored.

To determine which setting is applied first, the SSH client reads configuration sources in a specific, sequential order.

The Order of Evaluation

When you run an ssh command on Ubuntu, the client evaluates configuration sources in the following order, from highest priority to lowest priority:

1. Command-Line Options: Any options passed directly in the terminal command (using the -o flag or specific switches like -p for port) always take highest priority.
2. User-Specific Configuration: The client reads the user’s local configuration file located at ~/.ssh/config.
3. System-Wide Configuration: Finally, the client reads the global system-wide configuration file at /etc/ssh/ssh_config and any drop-in configuration files included from /etc/ssh/ssh_config.d/.

Because the user-specific configuration is read before the system-wide configuration, user settings always override system-wide settings.

Practical Example of Conflict Resolution

Consider a scenario where there is a conflict regarding the port number and the connection username for a remote server.

1. System-Wide Config (/etc/ssh/ssh_config)

The system administrator has defined global defaults:

Host *
    Port 22
    User ubuntu

2. User-Specific Config (~/.ssh/config)

An individual user has defined custom settings for a specific development server:

Host dev-server
    HostName 192.168.1.50
    Port 2222
    User developer

Resolution Outcome

When the user runs the command ssh dev-server, the SSH client resolves the settings as follows:

• HostName: The client reads ~/.ssh/config, finds HostName 192.168.1.50, and sets the destination.
• Port: The client reads ~/.ssh/config and sets the port to 2222. When it later reads /etc/ssh/ssh_config and encounters Port 22, it ignores it because a value for the port has already been set.
• User: The client sets the user to developer from the user config. The global default of ubuntu in the system config is ignored.

If the user wants to temporarily override both of these configurations, they can use the command line:

ssh -p 9999 admin@dev-server

In this case, the command-line arguments override both ~/.ssh/config and /etc/ssh/ssh_config, resulting in a connection to port 9999 as user admin.