// ssh config

SSH config wildcards and Host patterns: which rule wins?

Wildcards let one rule cover a whole domain. But SSH's precedence rules are subtle, and the obvious approach quietly offers two keys. Here's how to make the most specific host win.

Updated · 2 min read · by Pixel Worship, LLC

#The pattern syntax

Host lines take one or more patterns, separated by spaces:

PatternMatches
*Zero or more characters: *.example.com, or just * for everything
?Exactly one character: web-??.prod.example.com matches web-01… but not web-1…
!patternExcludes matching hosts from this block
a b cAny of several patterns

Two details catch people out:

  • *.example.com doesn't match example.com itself. Add it explicitly: Host example.com *.example.com.
  • Patterns match the name you typed (or the host in a git remote), not the HostName it resolves to.

#Rule 1: first value wins, top to bottom

For most options SSH takes the first value it finds in any matching block. So specific hosts go above general ones:

~/.ssh/config
Host legacy.example.com
  User admin          # wins for legacy.example.com

Host *.example.com
  User deploy         # every other subdomain

#Rule 2: IdentityFile is different

Here's the trap. IdentityFile doesn't follow "first wins". Every matching block adds its key:

~/.ssh/config
Host git.example.com
  IdentityFile ~/.ssh/work_ed25519

Host *.example.com
  IdentityFile ~/.ssh/id_ed25519

ssh -G git.example.com shows both keys, in order:

Output
identityfile ~/.ssh/work_ed25519
identityfile ~/.ssh/id_ed25519

If the first key fails, SSH tries the second. On GitHub that can mean logging in as the wrong account, and with several keys you can hit Too many authentication failures. Ordering alone can't fix this.

#The fix: exclude specific hosts from broader rules

Use ! so the wildcard doesn't apply where a more specific rule exists, and add IdentitiesOnly yes so the agent can't add extras:

~/.ssh/config
Host git.example.com
  IdentityFile ~/.ssh/work_ed25519
  IdentitiesOnly yes

Host *.example.com !git.example.com
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

Host * !git.example.com !*.example.com
  IdentityFile ~/.ssh/default_ed25519
  IdentitiesOnly yes

Now each host gets exactly one key:

You typeKey offered
git.example.comwork_ed25519
wiki.example.comid_ed25519
anything.elsedefault_ed25519

#Ranking "most specific"

With many rules, decide specificity consistently:

  1. Exact names before wildcards.
  2. More literal characters before fewer.
  3. Fewer * before more.

Then add every more-specific overlapping pattern as a ! exclusion on the broader line. That's tedious by hand. The SSH Config Generator does it for you in the browser.

#Check what SSH will really do

Terminal
ssh -G wiki.example.com | grep -E "^identityfile|^identitiesonly"

If you see more than one identityfile, a broader block is leaking a key.

#Let the app do the bookkeeping

EasySSHConfig applies exactly this ranking. You drag addresses (wildcards included) onto keys, and it writes every block with the right ! exclusions, so each host resolves to one key. A live "test a host" field shows which rule matched and what SSH will connect to.

Frequently asked questions

Does *.example.com match example.com?

No. The * needs the dot before example.com to be present, so the bare domain isn't matched. Add example.com as its own pattern: Host example.com *.example.com.

What does ! mean in an SSH Host line?

It excludes hosts. Host *.example.com !git.example.com applies to every subdomain except git.example.com. If any negated pattern matches, the whole line doesn't apply.

Do Host patterns match the HostName or what I type?

What you type on the command line (or in a git remote). HostName is the destination and isn't used for matching Host lines.

Can SSH use CIDR ranges like 10.0.0.0/8 in Host?

Not in Host lines. Use wildcard patterns such as 10.* instead. Match blocks with exec can do more complex tests.