skip to content

When does OpenSSH's ssh_config need a Match block instead of Host, and why must Match exec never see an attacker-chosen user or host name?

level: seniorimportance: nice to knowfreq 12%

answer

  1. Host sees only the typed name
  2. host versus originalhost
  3. a re-parse for the last pass
  4. exec runs a local shell command
  5. tokens expanded without quoting

basics

~20 s

Host matches only the typed name; Match tests other facts, such as the host after HostName substitution, the user, the local network or a command's exit status. Match exec expands tokens unquoted into a shell command, so a crafted name can inject commands.

solid answer

~50 s

`Host` compares patterns with the name typed on the command line. `Match` takes criteria: `host` (the target after `HostName` or canonicalization), `originalhost` (as typed), `user`, `localuser`, `localnetwork`, `tagged` (a `Tag` or `ssh -P`), `command`, `version`, `exec`, plus `canonical`, `final` and `all`. `Match final` asks for a re-parse and matches only in that last pass, so decisions can rest on values earlier blocks set. `Match exec` runs a command under your shell on the client and matches on exit status 0; tokens such as `%h` and `%u` are expanded without quoting, so a user or host name from an untrusted source can inject shell commands. OpenSSH 9.6 banned most shell metacharacters in command-line user and host names, 10.1 rejected control characters in user names, and 10.3 fixed validation that ran too late for `%u` in `Match exec`; the project says such mitigations cannot be absolute.

go deeper

for a junior

Recall that Match can test things Host cannot, such as the real host after HostName, the user or the local network.

for a middle

Explain host versus originalhost, what final's re-parse is for, and why Match exec tokens are dangerous with untrusted names.

for a senior

Show how you replace Match exec with static criteria, keep tokens out of shell commands, and review wrappers that build ssh command lines.

for a principal

Weigh clever conditional client config against a simpler explicit file that every engineer can read and audit.

## What Host cannot express A `Host` line compares its patterns with one thing: the **hostname argument as typed** on the command line. That covers aliases and wildcards, but not questions like "is the real target in this domain once `HostName` is applied", "am I on the office network", "which remote user is this" or "is this an sftp session". **`Match`** opens a section, ending at the next `Host` or `Match`, that applies only when **all** of its criteria are satisfied; each criterion may be negated with `!`. ## The criteria | Criterion | Tests | Typical use | |---|---|---| | `host` | target name after `HostName` or canonicalization | settings for every alias that resolves into a domain | | `originalhost` | the name as typed | same as `Host`, combinable with other criteria | | `user` / `localuser` | remote login / local account running ssh | per-account keys; system-wide rules | | `localnetwork` | CIDR ranges of active local interfaces | skip the bastion when on the internal network | | `tagged` | a name set by `Tag` or `ssh -P tag` | opt-in profiles chosen per run | | `command` | the remote command or subsystem requested | different options for `sftp` sessions | | `exec` | exit status of a local shell command | anything else, at a cost | | `canonical`, `final`, `all` | the re-parse passes; always true | ordering and catch-all blocks | Two notes from the manual are worth repeating. `localnetwork` is **not a trustworthy criterion** where addresses come from DHCP, so it should not gate security-sensitive settings. And `final` requests that the configuration be **re-parsed** regardless of `CanonicalizeHostname`, matching only during that final pass, which lets a block depend on the `HostName` an earlier block chose. ```ini Match host *.prod.internal.example !localnetwork 192.0.2.0/24 ProxyJump bastion-prod ``` Every alias whose `HostName` lands in production goes through the bastion, except when the laptop already sits on 192.0.2.0/24. The first-value rule still applies, so `Match` sections also belong above general defaults. ## Match exec: power and its price `Match exec "command"` runs the command **locally, under the user's shell**, during config parsing, and the condition is true when it exits with status 0. It accepts the `%` tokens, and the manual's TOKENS section warns that tokens are **expanded without quoting or escaping of shell characters**; the user must make sure they are safe. Two costs follow: 1. **Latency.** The command runs on every ssh invocation that reaches the block, including each `scp`, `sftp` and automation call. 2. **Injection.** If `%h`, `%r` or `%u` end up in the command and a user or host name comes from somewhere you do not control, such as a wrapper that builds ssh command lines from a ticket, a repository or a web form, a name containing shell syntax can run commands as you. ## How OpenSSH narrowed the hole - **9.6** banned most shell metacharacters from user and host names supplied on the command line, after finding that `ProxyCommand`, `LocalCommand` and `Match exec` expansions of them could inject commands. - **10.1** disallowed control characters in user names from the command line or `%` expansion. - **10.3** fixed validation of metacharacters in command-line user names that was performed too late to stop some `%` expansions, such as `%u` in `Match exec`. Values written literally in `ssh_config` are not subject to these checks, on the assumption that you wrote them. The release notes still recommend **against exposing ssh command lines to untrusted input**, because no filter can cover every shell and configuration. The defensive habits are simple: prefer static criteria (`host`, `user`, `localnetwork`, `tagged`) over `exec`, keep tokens out of `exec` commands, and validate names before any wrapper passes them to ssh. ## Choosing the right tool - If a decision depends only on the typed name, a `Host` block is simpler and faster to read. - If it depends on the real target after `HostName`, use `Match host`, adding `final` when the name is settled further down the file. - If it depends on where the laptop is, `localnetwork` avoids running a command, with the trust caveat above. - If a profile should apply only when asked for, `Tag` and `ssh -P` make the choice explicit on the command line. - Reach for `exec` last, and check the outcome of any of these with `ssh -G`, which prints the configuration after evaluating Match blocks.

  • `Host web1` sets `HostName web1.prod.internal.example`; later, `Host *.prod.internal.example` sets ProxyJump. Does `ssh web1` use the bastion?
    No. `Host` compares patterns with the typed name `web1`, which does not match the wildcard. `Match host *.prod.internal.example` would, because `host` is tested after `HostName` substitution; add `final` if `HostName` is only set further down the file.
  • Why is `Match localnetwork` a poor way to decide whether to skip a bastion for security reasons?
    It only inspects the client's own interface addresses, which anyone on a DHCP network can be handed or can set. The manual warns it is not a trustworthy criterion for security-sensitive settings; use it for convenience, and keep the server-side controls as the real boundary.

  • Host patterns are re-checked against the HostName after substitution
  • Match exec runs its command on the remote server
  • Match final means the block's values override earlier ones
  • OpenSSH 10.3 makes untrusted names safe in Match exec
  • Match localnetwork is a reliable security boundary

Assumes OpenSSH 10.5; 9.6 banned most shell metacharacters in command-line user and host names, 10.1 rejected control characters in user names, and 10.3 fixed late validation that let %u in Match exec be exploited.